Caddy静态站点常见问题排查手册

常见问题1：静态文件返回404

• 检查Caddyfile中root路径配置是否正确，绝对路径优先
• 检查文件权限：Caddy运行用户（www-data/caddy）必须有读权限
• 检查文件名大小写：Linux区分大小写，`Index.html`和`index.html`是不同文件
• 中文路径问题：确保文件系统编码为UTF-8，URL自动编码后可访问

常见问题2：HTTPS证书不自动签发

• 确认域名解析已指向服务器IP，80/443端口公网可访问
• 检查Caddy日志：`journalctl -u caddy -f` 看ACME申请错误
• 云服务器安全组放行80/443端口，无防火墙拦截
• 使用DNS challenge方式签发证书更稳定，无需公网端口

常见问题3：缓存不更新

• 静态资源加版本号：`style.css?v=timestamp` 强制刷新缓存
• 配置Cache-Control头：HTML短缓存（max-age=3600），静态资源长缓存（max-age=31536000）
• Caddy reload后旧缓存需要客户端硬刷新（Ctrl+F5）

常见问题4：重定向不生效

• 重定向规则顺序：精确路径优先，通配符放后面
• 301永久重定向会被浏览器缓存，测试时用302临时重定向
• 使用`redir`指令而非`rewrite`，rewrite是内部重写不改变URL