GitHub Actions 部署失败主因是路径问题：检查 images/ 是否提交、路径大小写是否一致、非根路径需加 <base> 标签；用 peaceiris/actions-gh-pages@v3 自动部署并确保 publish_dir 和触发路径正确；CSS 或图片 404 会导致对齐失效，需通过 Network 面板验证资源加载。
图片对齐后 HTML 渲染正常，但 GitHub Actions 部署失败？先看是不是路径问题
GitHub Actions 默认工作目录是仓库根目录，index.html 里用的 <img src="images/logo.png"> 这类相对路径，在本地双击打开可能正常（浏览器用 file:// 协议加载），但部署到 GitHub Pages 后必须走 HTTP 服务——如果 images/ 目录没被提交、或路径大小写不一致（比如实际是 Images/）、或用了绝对路径 /images/logo.png 却没配 base 标签，图片就会 404。
- 确认
images/目录已git add并推送到仓库（git status看一眼） - 检查 HTML 中所有
src和href路径是否全为小写、无空格、无中文 - 如果项目不是部署在根路径（比如用
username.github.io/repo-name），必须加<base href="/repo-name/">到<head>里，否则/images/会请求错位置
GitHub Actions 自动发布 HTML：用 gh-pages action 最省事
别自己写脚本推分支。直接用官方维护的 peaceiris/actions-gh-pages@v3，它自动把指定目录（比如 ./ 或 ./dist）推到 gh-pages 分支，并触发 GitHub Pages。
- 确保仓库 Settings → Pages → Source 选的是
gh-pages branch / (root) - 在
.github/workflows/deploy.yml里写：name: Deploy HTML on: push: branches: [main] paths: ["index.html", "images/**", "style.css"] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./ -
paths触发条件要包含图片目录（如images/**），否则改图不会触发部署
图片对齐失效？可能是 CSS 在 GitHub Pages 上没加载成功
本地预览时 CSS 生效，但部署后图片又左对齐了，大概率是 <link rel="stylesheet" href="style.css"> 的路径 404，或者 CSS 文件本身没提交。
- 打开浏览器开发者工具（F12），看 Network 标签页里
style.css是否返回 200；如果是 404，检查路径和文件名是否匹配（Linux 区分大小写） - 如果用了
@import引入其他 CSS，确保被导入的文件也在仓库中且路径正确 - 避免在 CSS 里用
url(../images/bg.jpg)这种向上跳级路径——GitHub Pages 不支持跨目录解析，一律改为相对于 CSS 文件的同级或子级路径
部署后图片模糊或尺寸错乱？检查 HTML 里的 width/height 和响应式设置
对齐本身不解决渲染质量。如果用了 <img width="200" height="100"> 但原始图是 400×200，浏览器会拉伸导致模糊；如果加了 max-width: 100% 但父容器没设宽，也可能撑满或收缩异常。
立即学习“前端免费学习笔记（深入）”；
- 优先用 CSS 控制尺寸：
img { width: 100%; height: auto; }，而不是 HTML 属性 - 确保图片本身分辨率足够——GitHub Pages 不做压缩，传什么显示什么
- 如果用了
<picture>或srcset，检查每个src路径是否都存在且可访问（Network 里逐个看）
GitHub Pages 不执行 JS、不读取本地 file:// 资源，所有路径必须真实存在于仓库中并能通过 HTTP 访问。最容易忽略的是大小写和 base 标签——尤其从 Windows 本地开发转到 Linux 构建环境时。
