GitHub Pages 静态网站部署：零成本全球托管实战指南

1. 这不是“部署”是把网站变成一张可全球访问的明信片你有没有试过写完一个 HTML 页面本地双击打开看着挺美但想发给朋友看——得压缩成 ZIP 发微信或者用网盘分享链接对方还得下载解压再点开这种“本地可见、网络难触”的状态就是绝大多数静态网站卡住的第一道墙。而Deploy a Static Website using Github这件事本质上不是在搞什么高深运维而是把你的 HTML/CSS/JS 文件通过 GitHub 的基础设施变成一张真正意义上的“数字明信片”它有固定地址比如https://yourname.github.io/project-name全球任意设备输入就能打开不依赖你电脑是否开机也不需要你租服务器、配 Nginx、学 Linux 命令。我第一次用这个方法上线个人作品集时连域名都没买就靠username.github.io这个免费子域名三天内收到 7 份设计岗面试邀约——不是因为页面多炫而是 HR 点开链接 0.8 秒就加载完成没弹任何安全警告手机端自动适配连我妈都能自己滑动看我的项目截图。核心关键词GitHub Pages就是这张明信片的邮局系统。它不是 GitHub 的附加功能而是深度集成在仓库底层的静态托管服务你 push 一次代码GitHub 自动触发构建流程如果用了 Jekyll 等生成器然后把编译后的纯 HTML 文件推送到全球 CDN 节点。整个过程不涉及 PHP 解释器、数据库连接、SSL 证书手动配置这些传统建站的“拦路虎”。它只认三样东西一个合法的 GitHub 仓库、一个符合规范的分支通常是main或gh-pages、以及根目录下至少一个index.html。没有后台语言没有运行时环境没有版本兼容焦虑——你写的什么用户看到的就是什么。适合谁前端初学者练手项目、开源文档站点、个人博客Jekyll/Hugo 驱动、产品落地页、简历主页、甚至嵌入式设备的本地管理界面通过 GitHub Pages GitHub API 实现轻量交互。它解决的从来不是“如何搭建复杂系统”而是“如何让想法以最轻量、最可靠、最零成本的方式第一时间被世界看见”。很多人误以为这只是一个“学生作业提交方案”其实恰恰相反Vercel、Netlify 这些现代前端托管平台的底层逻辑正是 GitHub Pages 模式的规模化升级。它们验证了同一个事实——对绝大多数内容型、展示型、营销型网站而言“静态即正义”。你不需要为每千次访问支付服务器费用不需要半夜被报警邮件惊醒更不需要在“网站打不开”时翻查 Apache 错误日志。你只需要专注写好 HTML 结构、CSS 样式、JS 交互逻辑剩下的交付、分发、缓存、HTTPS 全由 GitHub 托管。我带过的 32 个前端新人里有 29 个是在成功部署第一个 GitHub Pages 站点后才真正建立起“我写的代码能被真实用户使用”的职业信心。这不是技术降级而是交付路径的精准提效把本该花在环境配置上的 8 小时换成打磨用户体验的 8 小时。2. 整体设计思路为什么选 GitHub Pages 而不是其他方案2.1 不是“选它”而是“它天然匹配静态网站的本质需求”部署静态网站的核心诉求是什么不是“功能多强大”而是“确定性高、传播成本低、维护零负担”。我们来拆解三个典型替代方案的隐性成本自建服务器如阿里云 ECS Nginx表面看是“完全掌控”实则埋着三颗雷。第一颗是 HTTPS 证书续期——Let’s Encrypt 默认 90 天有效期你得写 cron 定时任务自动更新某次脚本出错或磁盘满全站立刻变不安全警告页第二颗是 DDoS 防御——哪怕只是被爬虫扫一下流量突增就可能触发云厂商的带宽限速用户访问直接超时第三颗是备份机制——你得定期 rsync 同步到对象存储还得验证备份文件能否正常解压还原。我曾帮一家教育公司迁移老官网他们用 ECS 部署了三年期间因证书过期导致家长无法查看课程表被投诉两次因未配置 Gzip 压缩移动端加载时间超 8 秒跳出率高达 76%。这些都不是技术难点而是持续运维的注意力税。第三方托管平台如 Vercel/Netlify它们确实比 GitHub Pages 更“智能”自动检测框架、一键部署、边缘函数支持、A/B 测试面板……但代价是“黑盒化”。当你发现某个 CSS 动画在 Netlify 构建后失效排查路径是检查本地构建产物 → 对比 Netlify 构建日志 → 查阅其文档中关于 PostCSS 版本的说明 → 提交 issue 等待回复。而 GitHub Pages 的构建日志是透明的见后续章节所有步骤可追溯。更重要的是它不绑定任何商业条款——Vercel 免费层限制每月 100GB 带宽超出后自动降级Netlify 免费版禁止私有仓库部署。而 GitHub Pages 对公开仓库完全免费且无带宽/请求次数限制仅单文件 ≤100MB总仓库 ≤1GB。我维护的 14 个开源文档站全部跑在 GitHub Pages 上其中threejs.org/examples的月均访问量超 200 万次CDN 响应时间稳定在 35ms 内从未触发过任何配额告警。本地预览工具如live-server、VS Code Live Server这根本不算“部署”只是开发阶段的临时方案。它解决不了跨设备访问问题手机连不上你电脑的 localhost:5500更无法做 SEO搜索引擎爬虫根本访问不到你的本地地址。我见过太多设计师把index.html发给客户说“这是最终版”结果客户用 iPhone Safari 打开字体渲染异常、Flex 布局错乱——因为本地预览用的是 Chrome 内核而客户用的是 WebKit。真正的部署必须经过真实网络环境的检验GitHub Pages 提供的正是这个“最小可行生产环境”。所以 GitHub Pages 的设计哲学非常朴素不做任何假设只做一件事——把 Git 仓库里的静态文件原样映射成 HTTP 可访问资源。它不解析 PHP不执行 Node.js不调用数据库不处理会话。这种“极简主义”恰恰成就了它的鲁棒性。你 push 的每个 commit都对应一个可回滚的部署快照你删除的每个文件都会在下次构建后彻底从线上消失。没有“缓存没刷新”的玄学问题没有“配置文件改错导致整站崩溃”的连锁反应。它像一台永不宕机的复印机你放进去什么原件它就输出什么复印件。2.2 方案选型背后的四个硬性约束条件我在给团队制定前端部署规范时会强制要求所有静态站点满足以下四条红线而 GitHub Pages 是目前唯一能 100% 满足的方案零配置 HTTPS 强制启用所有现代浏览器对非 HTTPS 站点标记“不安全”尤其涉及表单提交时会直接拦截。GitHub Pages 默认启用 TLS 1.3且自动续期证书。你无需生成 CSR、上传 PEM、配置 Nginx 的ssl_certificate指令。对比之下Cloudflare 免费版虽提供 HTTPS但需将 DNS 解析指向其代理服务器增加了单点故障风险而自建 Let’s Encrypt 则需手动维护 ACME 协议交互逻辑。Git 工作流原生集成开发者最自然的协作方式就是git add/commit/push。GitHub Pages 将push操作直接映射为部署事件中间无额外 CLI 工具、无 CI/CD YAML 配置、无 webhook 手动绑定。我曾让实习生用 GitHub Pages 部署公司内部知识库他只做了三步创建新仓库 → 把 HTML 文件拖进去 →git push origin main。整个过程耗时 92 秒比我教他配置 Vercel 的vercel.json还快。这种“无感部署”极大降低了新人的上手门槛。CNAME 域名无缝绑定当你需要docs.yourcompany.com这样的品牌域名时GitHub Pages 仅需两步在仓库设置中填入docs.yourcompany.com→ 在域名 DNS 中添加CNAME记录指向yourname.github.io。整个过程无需修改源码、无需重启服务、无需等待 CDN 缓存刷新。而某些平台要求你先在控制台添加域名再生成 TXT 验证记录最后还要手动上传 SSL 证书平均耗时 15 分钟以上。构建过程完全透明可审计每次部署失败GitHub Pages 都会在仓库的Settings Pages页面显示详细错误日志包括哪一行 Markdown 渲染失败如果你用 Jekyll、哪个图片路径 404、甚至index.html中link标签的 href 是否拼写错误。这种粒度的错误定位能力在 Vercel 的构建日志中往往被抽象为“Build failed”你需要点开详细日志逐行搜索关键词。对于追求交付确定性的团队这种“所见即所得”的调试体验价值远超自动化程度。提示GitHub Pages 并非万能。它明确不支持服务端渲染SSR、动态 API 调用需走 CORS 代理、WebSocket 长连接。如果你的网站需要实时聊天、用户登录态管理、个性化推荐它就不适合。但请诚实回答你当前这个项目真的需要这些能力吗还是只是被“标配功能”惯坏了3. 核心细节解析从仓库创建到全球可访问的完整链路3.1 两种部署模式的本质区别与选型指南GitHub Pages 提供两种基础部署模式它们决定了你的文件组织方式和访问路径选错会导致 404 或样式丢失User/Organization Pages用户/组织主页仓库名必须严格为username.github.io例如我的账号是zhangsan仓库名必须是zhangsan.github.io。部署后网站根 URL 就是https://username.github.io。这种模式强制使用main分支旧版支持master现已弃用且所有文件必须放在仓库根目录。优势是访问路径最短、SEO 权重最高根域名天然比子路径权重高劣势是每个 GitHub 账号只能有一个此类仓库且无法用于项目文档因为根目录要放全部网站文件。Project Pages项目主页仓库名可以是任意合法名称如my-portfolio、blog-hugo。部署后网站 URL 为https://username.github.io/repository-name例如https://zhangsan.github.io/my-portfolio。它支持两种分支策略gh-pages分支所有网站文件放在此分支的根目录main分支的/docs目录网站文件放在main分支的docs/子文件夹内。这种模式适合绝大多数场景你可以为每个项目单独建一个 Pages 站点互不干扰/docs目录方案还能让你把文档和源码放在同一仓库保持上下文一致。我强烈建议新手从Project Pages /docs目录开始。原因很实在你不需要新建仓库直接在现有项目里建个docs文件夹就行git push时不会影响主代码分支调试时删掉docs文件夹就能瞬间下线网站毫无副作用。我维护的vuepress-theme-vt插件文档就是用这个模式——源码在src/文档在docs/CI 流水线每次 merge 到main自动构建并推送docs/.vuepress/dist/到gh-pages分支全程无人值守。注意不要试图用main分支直接部署 Project PagesGitHub 会静默忽略你的网站永远 404。必须明确指定gh-pages分支或/docs目录。3.2 文件结构规范为什么你的 CSS 总是加载失败90% 的 GitHub Pages 部署失败根源在于相对路径写法错误。本地双击index.html时浏览器以文件系统为根file:///Users/you/project/index.html而 GitHub Pages 以 HTTP 为根https://user.github.io/repo/。这意味着本地有效的link relstylesheet hrefcss/style.css在 Pages 上会被解析为https://user.github.io/repo/css/style.css但如果仓库结构是project-root/css/style.css而你把index.html放在docs/目录下实际路径是https://user.github.io/repo/docs/index.html那么hrefcss/style.css就会变成https://user.github.io/repo/docs/css/style.css—— 多了一层/docs/必然 404。解决方案只有两个且必须统一绝对路径前缀法推荐在所有资源引用前加仓库名作为路径前缀。例如你的仓库叫my-portfolio则link relstylesheet href/my-portfolio/css/style.css img src/my-portfolio/images/avatar.jpg altme这样无论index.html在/还是/docs/浏览器都会从根域名开始解析路径。缺点是每次换仓库名都要批量替换但可通过构建工具如 Webpack 的publicPath自动注入。Base URL 声明法更优雅在index.html的head中添加base href/my-portfolio/此后所有相对路径css/style.css、images/logo.png都会自动拼接base值。注意末尾斜杠不能少否则会变成/my-portfoliocss/style.css。这种方法对纯 HTML 站点极其友好我所有手写页面都用它。实操心得用 VS Code 安装 “Auto Rename Tag” 插件开启editor.linkedEditing设置修改base标签时会自动同步更新所有href/src属性避免漏改。3.3 Jekyll 构建引擎当你的网站不只是 HTMLGitHub Pages 默认启用 JekyllRuby 编写的静态网站生成器这意味着它不仅能托管纯 HTML还能动态渲染.md、.html模板文件。当你在仓库中放入_config.yml文件Jekyll 就会启动# _config.yml 示例 title: My Portfolio theme: jekyll-theme-minimal plugins: - jekyll-include-cacheJekyll 的核心价值在于用数据驱动模板避免重复劳动。例如你想在首页和项目页都显示作者信息传统做法是复制粘贴两段 HTML而 Jekyll 允许你创建_data/authors.ymlzhangsan: name: 张三 role: 前端工程师 avatar: /images/zhangsan.jpg然后在任意页面用 Liquid 模板语法调用{% assign author site.data.authors.zhangsan %} h1{{ author.name }}/h1 p{{ author.role }}/p img src{{ author.avatar }} alt{{ author.name }}这样修改作者信息只需改一处 YAML 文件。Jekyll 还内置了文章归档、分类标签、分页导航等功能非常适合博客类站点。但要注意Jekyll 会忽略以_开头的文件和文件夹如_layouts/,_includes/这是它的约定。如果你的 CSS 文件叫_style.css它将不会被部署同样node_modules/、package-lock.json等开发文件也会被自动排除无需手动.gitignore。提示如果你不需要 Jekyll 功能只需在仓库根目录添加.nojekyll空文件GitHub Pages 就会跳过 Jekyll 构建直接托管原始文件。这对 Vue/React 项目构建产物dist/目录至关重要——否则 Jekyll 会尝试解析dist/index.html中的{%语法导致页面空白。4. 实操过程手把手完成一次零失误部署4.1 准备工作创建仓库与初始化文件我们以部署一个极简个人主页为例全程无需安装任何软件仅用浏览器操作登录 GitHub点击右上角→New repositoryRepository name 填my-portfolio注意不要用username.github.io那是 User PagesDescription 填 “My personal portfolio website”勾选 “Add a README file”生成初始 commit点击 “Create repository”。此时仓库已创建但还不能访问 Pages。进入下一步点击仓库顶部的Settings选项卡左侧菜单滚动到底部点击Pages在 “Build and deployment” 区域Source 选择 “Deploy from a branch”Branch 选择mainFolder 选择/ (root)因为我们用/docs目录这里先选 root稍后会改点击 “Save”—— 此时 GitHub 会提示 “Your site is ready to be published at https://username.github.io/my-portfolio”但别急现在还是 404因为根目录只有README.md。现在创建网站文件点击仓库主页的Add file→Create new file文件名填docs/index.html关键路径必须是docs/开头粘贴以下 HTML 内容!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleMy Portfolio/title base href/my-portfolio/ style body { font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto; margin: 0; padding: 2rem; } h1 { color: #333; } .card { background: #f8f9fa; border-radius: 8px; padding: 1.5rem; margin-top: 1rem; } /style /head body h1你好我是张三/h1 div classcard h2前端工程师 | 专注用户体验/h2 p用代码构建有温度的数字产品/p /div /body /html滚动到底部Commit changes默认 Commit message 即可。此时docs/index.html已存在但 Pages 设置还没指向/docs。回到Settings PagesBranch 区域Folder 改为/docs点击 “Save”。GitHub 会立即触发构建通常 30 秒内完成。页面会显示 “Your site is published at https://username.github.io/my-portfolio”。打开这个链接你应该看到一个干净的白色页面标题为“你好我是张三”。实测验证我刚在测试账号完成此流程从创建仓库到页面可访问耗时 2 分 17 秒。期间没有任何命令行操作完全浏览器内完成。402 更新网站内容一次git push的完整生命周期当你需要更新内容比如改标题、加新项目流程极其简单在本地克隆仓库git clone https://github.com/username/my-portfolio.git cd my-portfolio编辑docs/index.html用任意编辑器打开修改h1标签内容为 “你好我是李四”保存。提交并推送git add docs/index.html git commit -m update homepage title git push origin mainGitHub 接收 push 后的自动响应检测到main分支变更且docs/目录有文件变动触发 Pages 构建流水线构建器扫描docs/目录校验index.html语法HTML5 验证将docs/下所有文件含子目录打包推送至 GitHub 的全球 CDN 节点美国、欧洲、亚太各 3 个 PoP更新 DNS 缓存使新内容生效。整个过程无需人工干预。你可以在Settings Pages页面实时查看构建日志成功时显示绿色 “Build successful”失败时显示红色错误详情如 “File not found: docs/css/style.css”。注意事项GitHub Pages 构建有 10 分钟缓存期。如果你刚推送完就刷新页面还是旧内容不是部署失败而是 CDN 缓存未刷新。等待 10 分钟或强制刷新CtrlF5即可。若需立即生效可在docs/目录下添加空文件touch docs/.nojekyll并推送这会触发全量重建。4.3 绑定自定义域名三步实现品牌化访问假设你已购买域名mypersonal.site想让网站访问地址变为https://mypersonal.site在 GitHub 仓库的Settings Pages中Custom domain 输入框填mypersonal.site点击 SaveGitHub 会自动生成一个CNAME文件内容为mypersonal.site并提交到gh-pages分支或main分支的docs/目录。登录你的域名注册商如 Namecheap、腾讯云 DNS添加一条CNAME记录Host:或留空取决于注册商Value:username.github.io注意不是my-portfolio.github.io必须是 User Pages 的域名TTL: 自动通常 300 秒等待 DNS 生效通常 1-60 分钟GitHub 会自动为你的域名申请 Let’s Encrypt 证书通常在 DNS 解析生效后 2 分钟内完成。你可以在Settings Pages页面看到 “Enforce HTTPS” 开关开启后所有 HTTP 请求自动重定向到 HTTPS。关键细节GitHub Pages 要求自定义域名必须指向username.github.io而不是repository-name.github.io。这是因为 Pages 服务是按用户维度托管的所有该用户的仓库共享同一套 CDN 和证书体系。如果你绑错了会看到 “The page is not hosted by GitHub” 错误。5. 常见问题与排查技巧实录5.1 404 错误90% 的问题都出在这里现象根本原因排查步骤解决方案访问https://user.github.io/repo显示 404Pages 未启用或分支设置错误进入Settings Pages确认 Source 是否为 “Deploy from a branch”Branch 是否为main或gh-pagesFolder 是否为/docs若用 docs 目录点击 Save 重新保存设置等待 30 秒访问https://user.github.io/repo显示 “Site not found”仓库名不符合 Project Pages 规范检查仓库名是否为user.github.ioUser Pages或普通名称Project Pages若是 Project Pages确保仓库名 ≠user.github.io若是 User Pages确保仓库名严格匹配图片/CSS 加载失败控制台报 404资源路径未适配 Pages 的 URL 结构打开浏览器开发者工具 → Network 标签页查看失败请求的完整 URL对比文件实际存放路径使用base href/repo-name/或绝对路径/repo-name/css/style.cssindex.html能打开但子页面如/projects/404未启用 Jekyll 或缺少permalink配置检查仓库是否有_config.yml是否包含permalink: /:title/添加_config.yml并配置 permalink或直接用projects.html替代/projects/index.html独家技巧在docs/目录下创建一个test.txt文件内容为 “test ok”然后访问https://user.github.io/repo/docs/test.txt。如果能打开证明 Pages 服务正常问题一定出在index.html的路径或 HTML 结构上。5.2 样式/脚本失效那些看不见的陷阱CSS 不生效最常见原因是link标签的relstylesheet拼写错误写成relstyle或href路径中混用了反斜杠\Windows 风格。GitHub Pages 只认正斜杠/。实测我把hrefcss\style.css改成hrefcss/style.css样式立刻恢复。JavaScript 报错 “Cannot access ‘document’ before initialization”这是因为 JS 代码放在head中而 DOM 尚未加载。解决方案将script标签移到/body前或添加defer属性script srcapp.js defer/script或用DOMContentLoaded事件包裹document.addEventListener(DOMContentLoaded, () { // 你的代码 });图片显示为方块alt 文字检查图片文件名是否含中文或空格。GitHub Pages 对文件名编码敏感我的头像.jpg会被转义为%E6%88%91%E7%9A%84%E5%A4%B4%E5%83%8F.jpg而 HTML 中写的src我的头像.jpg无法匹配。解决方案文件名全部用英文小写短横线如my-avatar.jpg。5.3 构建失败读懂 GitHub 的错误日志GitHub Pages 构建失败时Settings Pages页面会显示红色错误框点击 “View build log” 可看到详细日志。典型错误及对策“Page build warning: Your site’s source is not set to a supported branch”说明你设置了gh-pages分支但仓库中不存在该分支。解决方案在终端执行git checkout -b gh-pages git push origin gh-pages创建分支。“Page build failed: A file was included in more than one place”Jekyll 检测到同一文件被多个模板引用可能导致循环渲染。检查_includes/目录下的文件是否被重复include。“Page build failed: Invalid value for ‘theme’ in _config.yml”_config.yml中指定的 theme 名称拼写错误或该 theme 不在 GitHub 官方主题列表中。访问 pages-themes.github.io 查看可用主题。实操心得我习惯在本地用jekyll serve启动预览服务需安装 Ruby 和 Jekyll这样能在推送前发现 90% 的构建错误。命令cd my-portfolio bundle exec jekyll serve --source docs --destination _site然后访问http://localhost:4000。5.4 性能优化让 Pages 加载快如闪电GitHub Pages 本身已启用 Brotli 压缩、HTTP/2、全球 CDN但你仍可做三件事提升首屏体验内联关键 CSS将首屏渲染必需的 CSS如字体、颜色、布局直接写在style标签中避免额外 HTTP 请求。剩余 CSS 用link relpreload预加载link relpreload href/my-portfolio/css/remaining.css asstyle onloadthis.onloadnull;this.relstylesheet图片懒加载为非首屏图片添加loadinglazy属性img src/my-portfolio/images/project1.jpg loadinglazy altProject 1移除未用 CSS使用 Chrome DevTools 的 Coverage 工具More Tools → Coverage录制页面加载查看 CSS 文件中未执行的代码行手动删除。我用这三招将一个 12 页的文档站 LCP最大内容绘制从 2.1s 降至 0.8s且所有操作都在 HTML 文件内完成无需构建工具。6. 进阶实践超越基础部署的生产力组合6.1 自动化部署用 GitHub Actions 实现“提交即上线”虽然手动git push已足够简单但当项目复杂度上升如 VuePress 生成静态文件手动操作易出错。GitHub Actions 可实现全自动构建部署在仓库根目录创建.github/workflows/deploy.ymlname: Deploy to GitHub Pages on: push: branches: [main] paths: [docs/**, _config.yml, README.md] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 - run: npm ci - name: Build docs run: npm run docs:build # 假设你的构建命令生成 dist/ 目录 - name: Deploy uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/.vuepress/dist此 workflow 监听main分支的docs/目录变更自动运行npm run docs:build并将构建产物推送到gh-pages分支。你只需git push源码Pages 自动更新。注意peaceiris/actions-gh-pages是社区最稳定的 Pages 部署 Action它会自动处理 CNAME 文件、跳过.git目录、保留历史提交比 GitHub 官方的actions/upload-artifact更可靠。6.2 多环境管理用分支隔离开发/测试/生产大型项目常需多环境dev分支用于日常开发staging用于 QA 测试main用于生产发布。GitHub Pages 支持为不同分支配置不同 Pages 站点在Settings Pages中Source 选择 “Deploy from a branch”Branch 选择devFolder 选择/docs点击 Save获得https://user.github.io/repo/dev实际 URL 会自动追加/dev重复此操作为staging分支配置获得https://user.github.io/repo/staging。这样开发人员 push 到devQA 团队立即测试dev站点测试通过后 merge 到staging产品经理验收最终 merge 到main生产环境更新。整个流程无需修改任何配置纯粹靠分支策略驱动。6.3 安全加固防止恶意内容注入GitHub Pages 本身是只读托管但若你允许用户提交内容如评论区需防范 XSS 攻击。最佳实践禁用用户可控的 JavaScript不要在页面中eval()用户输入或用innerHTML插入未过滤的 HTML使用 CSP内容安全策略在head中添加meta http-equivContent-Security-Policy contentdefault-src self; script-src self; style-src self unsafe-inline; img-src self data:;这会阻止所有外部脚本、内联事件处理器如onclick大幅提升安全性评论系统选型避免自建后端选用 GitHub Issues 驱动的静态评论如 Utterances、Giscus它们利用 GitHub OAuth无服务器风险。我负责的安全审计项目中所有 GitHub Pages 站点均通过此 CSP 配置成功拦截了 100% 的 XSS 扫描攻击。7. 我的实际经验从踩坑到建立标准流程我第一次部署 GitHub Pages 是在 2016 年当时为了给一个开源图标库做文档折腾了整整一天。问题出在三个地方第一我把仓库命名为icon-library.github.io误以为这是 Project Pages结果 GitHub 强制要求它必须是 User Pages导致无法绑定自定义域名第二我用main分支直接部署但没注意到 Pages 设置里 Folder 默认是/ (root)而我的文件在docs/目录下一直 404第三CSS 路径用了../css/style.css在 Pages 上解析成