1. 项目概述用 GitHub 托管静态网站不是“发个仓库”就完事“How to Deploy a Static Website using Github”——这个标题看似简单但背后藏着一个被大量新手严重低估的实操闭环。它不是教你怎么把 HTML 文件拖进 GitHub 仓库而是要解决一个真实问题如何让一份本地写的纯 HTML/CSS/JS 网站不买服务器、不装环境、不配域名5 分钟内变成全球可访问、带 HTTPS、自动更新、有稳定 URL 的线上产品。我从 2016 年开始用 GitHub Pages 做个人博客、项目文档、活动落地页到今天累计部署过 83 个不同用途的静态站点覆盖技术文档、开源工具介绍页、学生作品集、内部培训门户、甚至小型电商商品目录纯前端 第三方表单。核心关键词就是GitHub Pages、Jekyll、Custom Domain、CI/CD 自动构建、HTTPS 强制、CNAME 配置、404 页面定制——这些词不是装饰每一个都对应一个踩过坑、改过三次配置、查过五次官方文档才搞明白的实操节点。很多人以为“部署静态网站 git push”结果发现首页能打开点导航栏 404或者绑了域名HTTP 能进HTTPS 直接报错又或者改了 CSS刷新页面还是旧样式清缓存也没用。这些问题根本不是“不会操作”而是对 GitHub Pages 的运行机制缺乏基本认知它不是 FTP 上传而是一套基于 Git 提交触发、由 GitHub 服务器自动编译渲染、再分发到全球 CDN 的发布流水线。你本地写的 index.html 是“源码”GitHub Pages 最终给你的是“编译后产物”中间可能经过 Jekyll 渲染、插件处理、路径重写。所以这篇内容适合三类人刚学完 HTML 想上线第一个作品的学生做开源项目需要快速搭文档页的开发者以及团队里负责内部工具门户、需要零运维成本交付静态内容的前端或产品经理。它不讲抽象概念只讲你 push 前该删哪行、push 后该看哪条日志、报错时该查哪个设置页——所有内容我都已在生产环境反复验证过。2. 整体设计与思路拆解为什么选 GitHub Pages它到底替你干了什么2.1 不是“替代服务器”而是“接管构建分发安全”的全链路托管很多人纠结“GitHub Pages 和 Vercel、Netlify 有什么区别”其实这个问题本身就错了方向。Vercel 和 Netlify 是通用静态托管平台而 GitHub Pages 是 GitHub 生态的原生能力——它的价值不在于“能不能做”而在于“做了之后省掉多少协调成本”。我拿一个真实场景对比上周帮一个硬件创业团队部署产品说明书网站。他们用 MkDocs 写文档生成静态文件后需要把 build 目录压缩上传到对象存储如 AWS S3配置 CloudFront 分发并绑定自定义域名在 ACM 申请 SSL 证书并关联设置缓存策略、强制 HTTPS 重定向每次更新文档手动触发构建 上传 清缓存而用 GitHub Pages整个流程变成mkdocs build生成 site/ 目录把 site/ 内容提交到仓库 gh-pages 分支或 docs/ 目录GitHub 自动检测变更启动构建流程构建完成后自动推送到全球 CDN 节点自动签发 Let’s Encrypt 证书强制 HTTPS域名绑定只需在仓库 Settings → Pages 里填一行 CNAME提示GitHub Pages 的构建过程是黑盒的但它严格遵循规则。比如你用 Jekyll它会自动执行jekyll build --destination _site你用 Hugo它会调用hugo --destination _site如果你只是纯静态文件无构建步骤它直接把你的文件当最终产物分发。关键在于你提交的是“源码”GitHub Pages 输出的是“可访问的网站”中间那层转换逻辑必须由你明确告诉它怎么做。2.2 两种部署模式的本质差异gh-pages 分支 vs. main/docs 目录GitHub Pages 提供两种基础部署路径但它们的适用场景和限制完全不同选错会导致后续所有配置失效对比维度gh-pages 分支模式main/docs 目录模式适用项目类型独立项目网站如个人博客、产品官网开源库文档如 React、Vue 官方文档URL 格式https://username.github.io/repohttps://username.github.io/repo构建触发时机每次向 gh-pages 分支 push 新 commit每次向 main或默认分支push且 docs/ 下有变化构建控制权完全自主可放任意构建产物_site、dist、public受限仅识别 docs/ 下的文件不支持自定义构建命令典型使用场景用 VuePress 构建的文档站输出到 dist/再 push 到 gh-pages用 Sphinx 写的 Python 库文档源码和构建产物都放在 docs/我建议绝大多数新项目直接选gh-pages 分支模式。原因很实在第一你可以完全控制构建流程——比如用 GitHub Actions 先跑npm run build再把 dist/ 推到 gh-pages 分支这样连本地构建都省了第二避免 main 分支被文档文件污染代码和网站内容物理隔离第三调试方便你 push 到 gh-pages 的内容就是最终用户看到的内容所见即所得。而 docs/ 目录模式只推荐给那种“文档即代码”的小项目比如一个只有 3 个 Markdown 文件的工具说明页图省事直接扔 docs/ 下就行。2.3 为什么不用 GitHub Actions它和 Pages 原生构建是什么关系这里有个高频误解很多人以为“用了 GitHub Actions 就不用 GitHub Pages 了”。恰恰相反Actions 是增强 Pages 的不是替代它。GitHub Pages 原生构建只支持有限几种静态站点生成器Jekyll、Hugo、VuePress、Gatsby 等且版本固定、插件受限。而 Actions 让你获得完全自由的构建环境你可以用 Node.js 18、Python 3.11、Rust 1.75 —— 不受 GitHub Pages 默认环境限制可以安装任意 npm 包、pip 库、cargo crate可以执行 shell 脚本做文件重命名、SVG 压缩、图片懒加载注入可以在构建后自动推送产物到 gh-pages 分支实现“代码提交 → 自动构建 → 自动上线”闭环举个我实际用的例子一个用 Astro 构建的营销落地页。Astro 官方不支持 GitHub Pages 原生构建因为依赖最新版 Node但我用 Actions 写了 6 行 YAMLname: Deploy to GitHub Pages on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 18 - run: npm ci - run: npm run build - uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist这段脚本的意思是每次往 main 分支 push就拉代码 → 装 Node 18 → 装依赖 → 构建 → 把 dist/ 推到 gh-pages 分支。GitHub Pages 检测到 gh-pages 分支有更新立刻分发。整个过程全自动我只需要改代码、git push剩下的交给 Actions 和 Pages 协作完成。这才是现代静态网站部署的真实工作流。3. 核心细节解析与实操要点从零开始的每一步都藏着关键决策3.1 仓库初始化命名规则、公开性、初始文件选择新建仓库不是随便起个名字就完事。GitHub Pages 的 URL 规则决定了你的仓库名直接影响访问地址必须提前规划如果你要部署个人主页如https://yourname.github.io仓库名必须是yourname.github.io且必须是公开仓库Private 仓库不支持 Pages如果你要部署项目网站如https://yourname.github.io/my-project仓库名可以是任意合法名称如my-project但同样必须公开仓库描述建议写明用途比如 “Product landing page built with Astro”方便后续协作或自己回溯初始化时不要勾选 “Add a README file” 或 “Add .gitignore”。原因很实际README 会成为首页而你真正想展示的是 index.html.gitignore 里默认的规则如忽略 node_modules在 Pages 场景下反而可能误删构建产物。我习惯的做法是创建空仓库不初始化任何文件本地新建项目文件夹用你喜欢的方式初始化npm init -y、astro add、jekyll new .编写好 index.html 或配置好构建工具后再第一次 git push注意GitHub Pages 对仓库大小有硬限制1GB但更关键的是单文件不能超过 100MB。这意味着你不能把高清视频、大型 PSD 源文件直接放仓库里。我见过太多人把 200MB 的产品演示视频塞进 docs/ 目录结果 push 失败还找不到原因。正确做法是视频传到 Vimeo 或 YouTube嵌入 iframe大图用 WebP 格式压缩字体文件只保留 WOFF2 版本。3.2 构建产物目录选择_site、dist、public、docs哪个才是“真相”这是新手最容易卡住的环节。你用不同工具构建输出目录名五花八门Jekyll 默认_siteVue CLI 是distCreate React App 是buildAstro 是distDocusaurus 是website/build……但 GitHub Pages 只认一个事实它分发的是你最终提交到仓库里的那些文件。所以关键不是“工具默认输出哪”而是“你最终把哪些文件放到了可被 Pages 读取的位置”。回忆前面说的两种模式如果你用gh-pages 分支模式那么你 push 到 gh-pages 分支的根目录下的所有文件就是网站根目录。比如你构建出 dist/index.html、dist/css/main.css那你应该把整个 dist/ 目录里的内容不包括 dist/ 文件夹本身放到 gh-pages 分支的根下。如果你用main/docs 目录模式那么你必须确保 docs/index.html、docs/css/main.css 这样的路径存在Pages 才会把它当网站根目录。我推荐一个万无一失的操作流程以 VuePress 为例本地开发时vuepress dev docs查看效果构建vuepress build docs产物在.vuepress/dist/新建临时文件夹gh-pages-temp把.vuepress/dist/*全部复制进去注意是 *不是 dist/ 文件夹进入gh-pages-tempgit init git remote add origin your-repo-urlgit add . git commit -m deploygit push -f origin main:gh-pages强制推送到 gh-pages 分支这个流程确保你推上去的就是干净的、可直接访问的 HTML/CSS/JS 文件没有任何多余层级。很多人的 404 就是因为把整个 dist/ 文件夹推上去了导致实际路径变成https://xxx.github.io/dist/index.html而不是想要的https://xxx.github.io/index.html。3.3 自定义域名配置CNAME 文件、DNS 解析、HTTPS 强制的三重校验绑定自己的域名比如docs.yourcompany.com不是点几下鼠标就完事。它涉及三个独立系统协同工作GitHub Pages、你的 DNS 服务商、Let’s Encrypt 证书颁发机构。任何一个环节出错都会导致白屏或不安全提示。第一步在仓库里创建 CNAME 文件文件名必须是全大写CNAME无扩展名文件内容只有一行你的域名比如docs.yourcompany.com不能带 http://不能带 www. 前缀除非你明确要放在仓库根目录gh-pages 分支的根或 main 分支的根取决于你用哪种模式提交后GitHub Pages 后台会立即读取并生效通常 30 秒内第二步在 DNS 服务商配置解析记录这里极易出错。GitHub Pages 要求你配置A 记录不是 CNAME指向 GitHub 的 IP 地址 A 185.199.108.153 A 185.199.109.153 A 185.199.110.153 A 185.199.111.153注意不要用 CNAME 记录指向yourname.github.ioGitHub 明确不支持这种做法会导致 HTTPS 失败。A 记录是唯一被官方认证的方式。第三步等待并强制启用 HTTPSDNS 解析生效后通常 1-24 小时进入仓库 Settings → Pages → Custom domain输入你的域名点击 “Save”。GitHub 会自动向 Let’s Encrypt 申请证书。这个过程可能失败常见原因DNS 解析未生效用dig yourdomain.com检查是否返回上述四个 IP域名已存在其他 HTTPS 证书比如之前用过 Cloudflare需先停用域名包含通配符如*.docs.yourcompany.comGitHub 不支持一旦证书申请成功Settings 页面会出现 “Enforce HTTPS” 开关务必打开它。这是强制全站走 HTTPS 的最后保险。我见过太多人开了自定义域名但没开这个开关结果 HTTP 可访问HTTPS 直接 ERR_SSL_PROTOCOL_ERROR。4. 实操过程与核心环节实现手把手带你走完一次完整部署4.1 场景设定用纯 HTML/CSS/JS 部署一个产品介绍页零构建工具假设你已经用 VS Code 写好了一个单页产品介绍网站结构如下my-product-landing/ ├── index.html ├── css/ │ └── style.css ├── js/ │ └── main.js └── images/ └── hero.jpg现在要把它上线。步骤如下Step 1创建 GitHub 仓库并关联本地# 在 my-product-landing 目录下执行 git init git add . git commit -m initial commit git branch -M main git remote add origin https://github.com/yourname/my-product-landing.git git push -u origin mainStep 2启用 GitHub Pages 并选择源进入 GitHub 仓库 → Settings → Pages在 “Source” 下拉菜单中选择 “Deploy from a branch”Branch 选 “main”Folder 选 “/(root)”点击 Save此时 GitHub 会自动构建并给出访问地址https://yourname.github.io/my-product-landing/。注意末尾的/my-product-landing/这是子路径。如果你想去掉它即让网站在根路径访问必须用前面说的yourname.github.io仓库名。Step 3修复相对路径问题关键你本地测试时index.html 里可能是这样引用 CSSlink relstylesheet hrefcss/style.css但在 GitHub Pages 上如果仓库名是my-product-landing实际 URL 是https://yourname.github.io/my-product-landing/css/style.css这没问题。但如果某天你把仓库改名了所有路径就全挂了。更稳妥的做法是用根相对路径link relstylesheet href/my-product-landing/css/style.css或者更好的方式是用base标签统一基准路径head base hrefhttps://yourname.github.io/my-product-landing/ link relstylesheet hrefcss/style.css /head这样所有相对路径都以这个 base 为起点迁移成本极低。Step 4添加 404 页面提升体验GitHub Pages 默认 404 页面很简陋。你可以在仓库根目录创建404.html内容如下!DOCTYPE html html head titlePage Not Found/title meta http-equivrefresh content5;urlhttps://yourname.github.io/my-product-landing/ /head body h1Oops! Page not found./h1 pYoull be redirected to homepage in 5 seconds.../p a hrefhttps://yourname.github.io/my-product-landing/Go to homepage now/a /body /html只要文件名是404.html且放在根目录GitHub Pages 会自动捕获所有 404 请求并显示它。4.2 进阶场景用 GitHub Actions 自动化 Astro 构建部署Astro 是当前最轻量的静态站点生成器之一但它的构建依赖较新 Node 版本GitHub Pages 原生不支持。我们用 Actions 实现全自动Step 1初始化 Astro 项目npm create astrolatest my-astro-site -- --template basics cd my-astro-site npm installStep 2创建 Actions 工作流文件在项目根目录创建.github/workflows/deploy.ymlname: Deploy Astro Site on: push: branches: [main] permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: true jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-nodev4 with: node-version: 18 cache: npm - run: npm ci - run: npm run build - uses: actions/configure-pagesv4 - uses: actions/upload-pages-artifactv3 with: path: ./dist - uses: actions/deploy-pagesv4Step 3配置 Astro 输出路径修改astro.config.mjsexport default defineConfig({ output: static, // 必须是 static不是 SSR site: https://yourname.github.io/my-astro-site, // 替换为你的真实 URL });Step 4启用 GitHub Pages 并选择分支Settings → Pages → Source → “GitHub Actions”保存后Actions 会自动触发构建完成后 Pages 会从 Actions 产物中拉取文件这个流程的好处是你完全不用手动 push 构建产物所有操作都在 main 分支完成。Actions 日志清晰可见每一步执行情况构建失败时会发通知比手动操作可靠十倍。4.3 域名绑定实战从购买域名到全站 HTTPS以在 Namecheap 购买docs.myapp.com为例Step 1在 Namecheap 控制台添加 A 记录登录 Namecheap → Dashboard → Manage Domains → 选中myapp.com→ Advanced DNS点击 “Add New Record” → Type 选 “A Record”Host 填docs表示docs.myapp.comValue 填185.199.108.153重复四次填四个 A 记录TTL 保持默认AutomaticStep 2在 GitHub 仓库设置 CNAME在仓库根目录main 分支创建文件CNAME内容为docs.myapp.com提交并 pushStep 3等待 DNS 生效并启用 HTTPS用终端执行dig docs.myapp.com确认返回上述四个 IP等待 1-2 小时Namecheap 通常较快进入 GitHub Pages Settings → Custom domain → 输入docs.myapp.com→ Save几分钟后页面出现 “Enforce HTTPS” 开关立即开启实测心得DNS 生效后GitHub 证书申请通常在 2 分钟内完成。但如果之前该域名用过其他 HTTPS 服务如 NetlifyLet’s Encrypt 可能因速率限制拒绝签发这时需要等 1 小时再试。我一般会先用https://docs.myapp.com测试如果显示 “Your connection is not private”说明证书还没好刷新几次或等几分钟即可。5. 常见问题与排查技巧实录那些文档里不写、但你一定会遇到的坑5.1 404 问题排查速查表现象可能原因排查方法解决方案https://user.github.io/repo/打开是 404Pages 未启用或源分支错误进入 Settings → Pages确认 “Source” 已选中且状态为 “Your site is ready to be published”点击 Save 重新触发构建首页能打开但/css/style.css404CSS 路径错误或文件未提交打开浏览器开发者工具 → Network 标签看哪个资源返回 404检查仓库里是否有该文件路径用git ls-tree -r gh-pages -- css/确认文件是否存在修正 HTML 中的 href绑定域名后http://docs.myapp.com可访问https://报错HTTPS 未强制或证书未签发访问https://docs.myapp.com看浏览器地址栏是否有锁图标检查 Pages Settings 是否显示 “Enforce HTTPS” 已开启等待证书签发最多 24 小时确认 DNS A 记录正确开启强制 HTTPS本地index.html点击链接跳转正常GitHub Pages 上点击 404使用了file:协议或绝对路径查看 HTML 源码搜索file://、C:/、/Users/等本地路径全部替换为相对路径或根路径/repo/path/to/file.html我遇到最隐蔽的一次 404是因为在 CSS 里用了background: url(../images/hero.jpg)但实际文件在images/hero.jpg少了一级 ../。本地服务器自动纠错GitHub Pages 严格按路径找直接 404。解决方案很简单用git ls-tree -r gh-pages -- images/确认文件是否存在再用浏览器 Network 面板看具体哪个请求失败。5.2 构建失败日志解读指南GitHub Pages 原生构建失败时错误信息藏在两个地方Pages Settings 页面底部有 “Last build” 时间和状态点 “View build log” 可看详细日志仓库的 Actions 标签页如果用了 Actions所有构建日志都在这里常见错误日志及含义Error: The variable {{ site.url }} was not properly closed with }}→ Jekyll 模板语法错误检查_config.yml或 Markdown 文件中的 Liquid 语法Error: File to import not found or unreadable: variables→ Sass/SCSS 文件路径错误检查import语句中的路径是否相对于当前文件Error: Cannot find module autoprefixer→ 构建工具依赖缺失说明你用了自定义构建但没在 Actions 中安装依赖The page build failed for thegh-pagesbranch with the following error: Page build failed.→ 最笼统的错误必须点开日志看具体哪一行报错。90% 的情况是_config.yml格式错误比如用了 tab 缩进而不是空格实操心得我养成了一个习惯——每次改完_config.yml或模板文件先在本地用jekyll serve跑一下确认无报错再 push。GitHub Pages 的构建环境是只读的很多本地能跑的插件如 jekyll-redirect-from在 Pages 上默认禁用必须在_config.yml中显式声明plugins: [jekyll-redirect-from]。5.3 缓存问题终极解决方案GitHub Pages 使用全球 CDN缓存非常激进。你改了 CSS用户可能 24 小时后才看到新样式。这不是 bug是设计。解决方案有三个层次第一层强制刷新临时用户端CtrlF5Windows或 CmdShiftRMac强制重载开发者端在浏览器 Network 面板勾选 “Disable cache”第二层版本化文件名推荐在构建工具中启用文件哈希比如 Webpack 的[contenthash]Vite 的rollupOptions.output.entryFileNames: assets/[name].[hash].js。这样每次内容变文件名就变彻底绕过缓存。第三层配置 Cache-Control高级GitHub Pages 不允许自定义 HTTP 头但你可以用.nojekyll文件配合 JavaScript 动态加载资源。不过对大多数项目第二层已足够。我所有项目都默认开启文件哈希CSS 文件名类似style.abc123.css改一行代码文件名就变用户永远拿到最新版。5.4 安全与合规注意事项GitHub Pages 是公开服务所有内容默认可被搜索引擎索引。如果你部署的是内部文档或测试页面必须主动防护禁止搜索引擎抓取在index.html的head中添加meta namerobots contentnoindex, nofollow基础访问控制GitHub Pages 本身不支持密码保护但你可以用 JavaScript 做简单校验不安全仅防误点script const pwd prompt(Enter password); if (pwd ! your-secret) { document.body.innerHTML h1Access Denied/h1; throw new Error(Wrong password); } /script敏感信息零容忍.env文件、API 密钥、数据库连接字符串绝对不能提交到仓库。GitHub 会自动扫描并邮件警告严重者封禁仓库。我所有项目都用 GitHub Secrets 存储密钥Actions 中通过${{ secrets.API_KEY }}引用。最后分享一个血泪教训去年帮客户部署后台管理界面纯前端 mock 数据我把config.js里写了const API_URL https://dev-api.example.com结果客户误传到公开仓库第三方扫描器当天就抓到并报告。虽然没造成实质泄露但信任度大打折扣。现在我的规则是所有配置项必须从环境变量或构建时注入源码里绝不出现任何 URL、token、key 字样。我在实际部署中发现最耗时间的从来不是技术本身而是对 GitHub Pages 运行边界的理解。它不是一个万能 FTP而是一个有明确规则的自动化流水线。你提交什么它就分发什么你配置什么它就执行什么。没有玄学只有规则。只要把 CNAME 文件放对位置、A 记录配对 IP、构建产物路径理清剩下的就是等待和验证。这个过程教会我的不是怎么部署网站而是怎么和一个高度自动化的系统建立确定性协作——每一次 push都是你对规则的一次确认每一次访问都是系统对你承诺的兑现。
