GitHub Actions + GitHub Pages 自动部署需确保 workflow 文件路径正确、触发分支匹配、Actions 功能启用；构建产物目录（如 dist/ 或 public/）必须被正确指定并生成，Pages 设置中源须选“GitHub Actions”，静态资源需通过改名或加版本参数规避 CDN 缓存。
GitHub Actions + GitHub Pages 是当前最省心的 HTML 自动构建与静态资源替换方案，无需服务器、不配 Nginx、5 分钟就能上线——但前提是 dist/ 目录真被生成出来，且 actions/deploy-pages 拿到的是正确路径。
触发失败：push 后 workflow 没反应
常见错误现象是改完 index.html 一推代码，Actions 页面空空如也，连“queued”都不出现。
- 检查
.github/workflows/deploy.yml是否在仓库根目录下，路径错一个字符（比如写成.github/workflow/少个 s）就完全不识别 - 确认触发分支匹配：若用
main推送，但 workflow 写的是branches: [master]，就不会触发 - GitHub Free 账号对私有仓库默认禁用 Actions，需进 Settings → Actions → General → “Allow all actions” 手动开启
构建成功但页面 404 或内容陈旧
日志显示 Deploy to GitHub Pages 步骤绿色通过，但打开 Pages 链接仍是老版本，或直接 404。
- 重点看
actions/upload-pages-artifact的path参数：它必须指向实际构建产物目录，比如 VuePress 输出在public/，就不能写dist/ - GitHub Pages 设置里，Publishing source 必须选 “GitHub Actions”，而不是 “
/ (root)” 或 “/docs” —— 后两者会绕过 workflow，直接读源码 - 浏览器强刷（
Ctrl+Shift+R）仍看到旧内容？不是缓存问题，而是 Pages CDN 还没同步完，等 30–60 秒再试；若超 2 分钟未更新，说明 artifact 上传为空（常见于构建命令漏执行）
静态资源替换失败：新图表没刷新
你用脚本生成了新 chart.png 放进 assets/，但部署后页面还是旧图，右键“查看图像地址”发现 URL 没变。
立即学习“前端免费学习笔记（深入）”；
- GitHub Pages 默认启用 HTTP 缓存，对
.png、.js等静态资源返回Cache-Control: max-age=31536000（一年），浏览器根本不会重拉 - 解决方法只有两个：
chart.png?v=20260701加查询参数，或改文件名（如chart-20260701.png）——后者更可靠，因为 CDN 缓存基于完整 URL - 别指望靠修改
index.html时间戳触发刷新：Pages 不感知源文件修改时间，只认 artifact 内容哈希是否变化
Linux 自建服务器部署时 rsync 失败
用 git push 触发 post-receive 钩子执行 rsync，结果报错 permission denied 或目标目录为空。
-
rsync命令中源路径末尾必须加/（如/var/www/site.git/checkout/），否则会把整个checkout目录复制进去，导致index.html实际在/var/www/html/checkout/ - 确保钩子脚本以
deploy用户身份运行（而非git），并在/etc/passwd中确认该用户 shell 是/bin/bash，不是/usr/sbin/nologin -
rsync -av --delete很危险：若checkout/目录临时为空（比如构建失败），它会清空/var/www/html/—— 建议加--dry-run先测试，或用rsync -av --delete-after降低风险
最容易被忽略的点：所有构建步骤（npm run build、hugo、python generate_report.py）都必须显式声明输出目录，并确保该目录在 upload-pages-artifact 或 rsync 前已存在且非空；没人会替你检查 ls dist/，但 CI 不会说“你少了个 build 步骤”，它只会安静地部署一个空目录。
