GitHub Pages 原生不支持 Git LFS，导致本地（Live Server）能正常显示的图片在部署后失效；正确方案是改用 GitHub Actions 自定义工作流，并显式启用 lfs: true 的 checkout 步骤。
github pages 原生不支持 git lfs，导致本地（live server）能正常显示的图片在部署后失效；正确方案是改用 github actions 自定义工作流，并显式启用 `lfs: true` 的 checkout 步骤。
当你在本地使用 Live Server 预览网站时图片一切正常，但部署到 GitHub Pages 后所有图片 404——这通常不是路径写错，而是根本性机制限制：GitHub Pages 的静态资源并非直接从 Git 仓库读取，而是由 Pages 构建服务生成快照并托管，而该服务完全忽略 Git LFS 指针文件，不会下载 LFS 托管的大文件（如高清图、SVG、视频等）。
✅ 正确解决路径：切换至 GitHub Actions 部署
GitHub 官方明确表示「无计划支持 Git LFS for GitHub Pages」，但自 2022 年起已开放通过 GitHub Actions 自定义构建与发布流程，从而绕过原生限制。以下是关键三步：
1. 修改 Pages 发布源设置
进入仓库 → Settings → Pages → Build and deployment → Source
将 Deploy from a branch 改为 Deploy from a GitHub Actions workflow。
2. 添加或配置 Actions 工作流
在项目根目录创建 .github/workflows/pages.yml（或复用 官方 starter workflow），核心在于 actions/checkout 步骤必须启用 LFS：
name: Deploy to GitHub Pages
on:
push:
branches: ["main"] # 替换为你实际的源分支
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
with:
lfs: true # ⚠️ 关键！必须显式开启 LFS 下载
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: "18"
- name: Build (if needed)
run: npm ci && npm run build # 若含前端构建（如 Vite/React），保留此步；纯静态 HTML 可跳过
- name: Upload artifact
uses: actions/upload-pages-artifact@v2
with:
path: './' # 或 './dist' 等实际输出目录? 提示：若项目为纯静态 HTML/CSS/JS（无构建步骤），可删除
Setup Node和Build步骤，直接上传根目录。
3. 验证与注意事项
- ✅ 确保 Git LFS 已正确追踪图片文件：运行
git lfs track "*.png"等命令，并提交.gitattributes - ✅ 推送前执行
git lfs push --all origin，确保 LFS 对象已同步至远程 - ❌ 不要依赖相对路径调试：
./images/photo.jpg在 Actions 中需与仓库结构一致；建议统一使用根相对路径（如/images/photo.jpg）并确认文件位于仓库根目录下对应位置 - ⏱️ 首次 Actions 部署可能需 1–2 分钟，完成后访问
https://<username>.github.io/<repo></repo></username>即可验证图片是否加载
总结
Git LFS 与 GitHub Pages 的不兼容是平台级设计限制，而非配置错误。放弃“修改路径”或“重试推送”的无效尝试，果断迁移至 GitHub Actions 工作流，并在 checkout 步骤中声明 lfs: true——这是目前唯一稳定、官方支持且无需额外费用的解决方案。
