如何在 GitHub Pages 上正确引用网站本地文件（图片、文档等）？

在 github pages 上部署静态网站时，所有被 html 引用的资源（如图片、pdf、css、js 等）必须一并提交到仓库并公开，否则访问者将看到 404 错误；github pages 不支持后端服务，无法动态提供私有文件。

当你在本地开发一个网站（例如首页嵌入 Canva 导出的 PNG 图片，并通过 下载报告 链接到本地 pdf 文件），这些资源不会自动“跟随”html 一起上线——它们只是你电脑上的文件。要让访客正常查看或下载，你必须主动将这些文件纳入 gitHub 仓库，并确保路径引用准确。

✅ 正确做法：静态资源与代码一同发布

1. 组织项目结构（推荐）
   将资源分类存放，例如：

   my-website/ ├── index.html ├── style.css ├── script.js ├── assets/ │   ├── images/ │   │   └── hero-banner.png   ← 你的 Canva 图片 │   └── docs/ │       └── report.pdf        ← 你链接的文档

2. 在 HTML 中使用相对路径引用

   @@##@@ 查看完整报告

3. 提交全部文件到 github
   使用 git add .（或明确添加 assets/ 目录），再 git commit -m “add images and docs” → git push。只有出现在仓库中的文件，GitHub Pages 构建后才会托管并可被公网访问。

❌ 常见误区与风险

• 不要引用绝对本地路径：如 file:///Users/you/project/report.pdf 或 C:imageslogo.png —— 浏览器会直接拒绝加载，且 GitHub 完全无视此类路径。
• 不要依赖“仅自己可见”的文件：一旦文件被 HTML 引用并推送到公开仓库，它就对所有人可见（包括 PDF 内容、原始图片等）。若含敏感信息，请勿上传，或改用私有仓库（但注意：GitHub Pages 不支持私有仓库的免费托管，仅限付费团队版）。
• 不要幻想“后台代理”：GitHub Pages 是纯静态托管（无 node.js、php、数据库等后端能力），无法像 Vercel 或 Netlify Functions 那样通过 API 动态返回文件。所谓“隐藏文件路径”在此场景下无效。

? 验证是否成功？

部署后，直接访问资源 URL 测试：
? https://yourname.github.io/my-website/assets/images/hero-banner.png
若返回图片，则路径正确；若显示 404，则检查：

• 文件是否真的 git push 到远程仓库（可在 GitHub 网页端确认该路径存在）；
• src/href 路径是否拼写错误（区分大小写！）；
• 是否误将文件放在 .gitignore 中（常见于 ide 自动生成的缓存文件夹）。

? 替代方案（如需真正私有分发）

若确实需要限制文件访问（如仅授权用户下载 PDF），静态托管无法满足，此时应：

• 迁移至支持后端的平台（如 Vercel + serverless Functions、Cloudflare Pages + Durable Objects）；
• 或使用云存储（如 Cloudinary 存图、AWS S3 + 预签名 URL 分发 PDF），前端通过受控接口获取资源链接。

总之，GitHub Pages 的核心原则是：所见即所存，所链即所传。把文件放进仓库、路径写对、推送到远程——访客就能看到；反之，必报错。清晰理解这一机制，是构建可靠静态网站的第一步。