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

在 github pages 上部署网站时，所有被 html 引用的资源（如图片、pdf、css、js 等）必须随网站一同发布到仓库中；否则访问者将看到 404 错误——github pages 是纯静态托管，不支持服务端动态读取未提交的私有文件。

在 github pages 上部署网站时，所有被 html 引用的资源（如图片、pdf、css、js 等）必须随网站一同发布到仓库中；否则访问者将看到 404 错误——github pages 是纯静态托管，不支持服务端动态读取未提交的私有文件。

当你在本地开发网站并使用 Canva 导出的图片（例如 hero-banner.png），或添加了指向 ./documents/resume.pdf 的超链接时，这些路径只是相对引用。它们能否在真实访问中生效，完全取决于对应文件是否已推送到 GitHub 仓库，并位于正确的目录结构下。

✅ 正确做法：资源与代码共发布

GitHub Pages 托管的是静态网站，即仅通过 HTML、CSS、JavaScript 和静态资源（图片、字体、PDF 等）构成，所有被引用的文件都必须显式提交到仓库中。例如：

my-website/
├── index.html
├── style.css
├── script.js
├── assets/
│   └── hero-banner.png   ← Canva 图片放在这里
└── documents/
    └── resume.pdf        ← 其他可下载文件也需提交

在 index.html 中应使用相对路径引用：

<!-- 正确：路径与实际仓库结构一致 -->
<img src="assets/hero-banner.png" alt="首页横幅">
<a href="documents/resume.pdf" target="_blank">下载我的简历</a>

✅ 提交后推送到 GitHub（如 main 或 gh-pages 分支），GitHub Pages 自动构建并提供所有已提交文件的公开 HTTP 访问地址（如 https://username.github.io/my-website/assets/hero-banner.png）。

Joker AIx

一站式AI创意生产平台，覆盖图像、视频、音频、文案全品类创作

下载

❌ 常见误解与风险

• “文件在我电脑上，链接就能用” → 错误。浏览器无法访问你本地硬盘上的文件；链接必须指向服务器（即 GitHub 仓库）上真实存在的路径。
• “我把图片存在 Canva 云端，直接贴 Canva 链接” → 不推荐。Canva 分享链接通常带登录跳转、防盗链限制或临时失效，且不符合静态站点可靠性要求；应下载原图后上传至仓库。
• “我只上传 HTML，其他文件留本地” → 必然导致 404。用户点击链接或加载图片时，浏览器向 GitHub Pages 发起请求，而该路径下无文件，返回 404 Not Found。

⚠️ 关于“私有文件”的重要提醒

GitHub 仓库默认是公开的。一旦你将 resume.pdf、notes.docx 或任何文件推送到公开仓库，它们就对全网可见（即使你没在网页中链接它们）。
若文件含敏感信息（身份证号、内部数据、未授权素材），请：

• ✅ 使用 .gitignore 排除，绝不提交；
• ✅ 改用私有仓库（GitHub Free 用户可创建私有仓库，但 GitHub Pages 仅支持公有仓库托管）；
• ✅ 或改用支持私有静态托管的服务（如 Vercel、Netlify，配合访问令牌或密码保护）。

? 补充说明：为什么不能用后端动态提供文件？

你可能想到：“能否写个脚本，让用户点击时才从我电脑发文件？”——这需要运行中的后端服务（如 Node.js/Python 服务器），而 GitHub Pages 明确不支持服务端执行（截至 2024 年仍为纯 CDN 静态分发）。Stack Overflow 等权威来源多次确认：GitHub Pages has no server-side processing。因此，所有资源必须预置、静态化、版本化。

✅ 最佳实践总结

只要遵循“所见即所传”原则——网页中能看到什么，仓库里就必须有什么——你的 GitHub Pages 网站就能稳定、可靠、可重现地运行。