1. 从代码仓库到个人门户为什么选择GitHub Pages如果你手头有一些写好的HTML、CSS和JavaScript文件想找个地方放上去让全世界都能访问第一个想到的可能是去买个虚拟主机或者云服务器。但说实话对于个人项目、技术博客、作品集或者开源项目的文档站来说这有点“杀鸡用牛刀”了。配置环境、管理服务器、担心安全这些运维工作会迅速消耗掉你对创作的热情。而GitHub Pages本质上就是GitHub提供的一项免费服务它能自动将你仓库里的特定分支通常是main或gh-pages或者/docs文件夹下的静态文件构建并发布成一个可以通过https://username.github.io或自定义域名访问的公开网站。这个“静态”是关键。它指的是网站由纯粹的HTML、CSS、JavaScript、图片等文件构成不需要像PHP、Python、Node.js这样的服务器端语言在访问时动态生成页面。这意味着它极度轻量、安全没有数据库或后端代码被攻击的风险并且速度飞快因为GitHub会通过CDN内容分发网络将你的网站文件分发到全球各地。对于开发者来说这简直是天作之合你用来管理代码版本的Git仓库摇身一变成了网站的发布平台。每次你git push代码GitHub就会在后台自动帮你完成构建和部署几分钟后刷新页面就能看到更新。这种开发体验的流畅性是传统FTP上传无法比拟的。我最初用它来托管个人博客和技术文档后来发现它的应用场景远不止于此开源项目的演示页面、活动宣传页、在线简历、甚至是一些轻量级的小工具前端界面都是绝佳的用武之地。更重要的是它完全免费没有流量限制当然有合理使用条款对于个人和小型项目来说几乎是零成本建立网络存在的首选方案。2. 核心概念与两种发布模式详解在动手之前必须理清GitHub Pages的两种主要发布模式这决定了你仓库的结构和后续的工作流程。选择哪种模式取决于你的项目性质和个人习惯。2.1 用户/组织站点 vs. 项目站点这是最根本的分类对应着不同的访问地址和仓库命名规则。用户或组织站点这是你的“主站”。它的访问地址固定为https://username.github.io或https://orgname.github.io。要创建它你必须创建一个名为username.github.io的特殊命名仓库。例如我的GitHub用户名是zhangsan那么我就需要创建一个名为zhangsan.github.io的仓库。这个仓库的main分支或你设置的发布源分支根目录下的内容将直接构成你的主站。注意一个GitHub账户只能有一个用户或组织站点。这个站点通常用于个人博客、作品集等代表你个人的内容。项目站点这是为某个特定的代码仓库服务的站点。它的访问地址是https://username.github.io/repository-name。例如我有一个名为my-cool-project的仓库那么它的项目站点地址就是https://zhangsan.github.io/my-cool-project。任何仓库都可以通过开启GitHub Pages功能并指定源分支如main分支下的/docs文件夹或gh-pages分支来成为一个项目站点。实操心得我强烈建议将个人主站username.github.io和各个项目站点分开。主站仓库只存放博客或作品集本身保持整洁。各个项目站点则专注于展示该项目本身这样结构清晰互不干扰。很多人一开始会混淆试图在项目仓库里建个人博客后期迁移起来会很麻烦。2.2 发布源的选择分支、文件夹与构建流程确定了站点类型接下来要决定从哪里发布你的网站文件。GitHub Pages提供了几个选项从main分支的根目录发布这是最直接的方式。你的网站文件如index.html就直接放在仓库的根目录。每次推送main分支网站就更新。适合纯静态、无需构建的简单网站。从main分支的/docs文件夹发布你的网站文件全部放在仓库根目录下的docs文件夹里。这样做的好处是可以将网站文档和项目的源代码放在同一个仓库但不同目录方便管理。很多开源项目喜欢用这种方式托管文档。从gh-pages分支发布这是一个专门用于托管网站内容的分支。你的main分支存放源代码而构建生成的静态文件例如通过Jekyll、Hugo、Vite等工具生成被推送到gh-pages分支。这是最灵活、也是最推荐给现代前端项目的方式因为它实现了源码和产物的完全分离。关于构建流程GitHub Pages原生支持Jekyll这是一个用Ruby写的静态网站生成器。如果你使用Jekyll并且仓库里包含了_config.yml等Jekyll配置文件当你推送源码到main分支时GitHub会自动识别并运行Jekyll构建将生成的静态网站发布出去。对于非Jekyll项目比如Vue、React应用你需要先在本地完成构建然后将构建输出目录如dist,build,out下的所有文件推送到你设置的发布源比如gh-pages分支或/docs文件夹。GitHub不会为你运行npm run build这样的命令。为什么我推荐使用gh-pages分支因为它干净。你的main分支历史记录里不会充斥着一堆构建后生成的、难以阅读的main.abc123.js文件。你可以用.gitignore忽略本地的构建目录然后在本地通过一个脚本或GitHub Actions自动构建并将结果推送到gh-pages分支。很多前端框架的官方文档都提供了相应的部署脚本。3. 手把手实战从零发布一个React应用理论说再多不如动手做一遍。我们以创建一个React应用并发布到GitHub Pages项目站点为例走通全流程。这里假设你已安装Node.js、npm和Git。3.1 本地项目创建与初始化首先我们在本地创建一个新的React应用。打开终端执行npx create-react-app my-github-pages-demo cd my-github-pages-demo这会创建一个标准的React项目。接下来我们需要安装一个非常关键的辅助包gh-pages。它可以帮助我们轻松地将构建好的文件部署到gh-pages分支。npm install --save-dev gh-pages安装完成后打开package.json文件我们需要添加两个字段。首先在文件顶部添加一个homepage字段。这个字段至关重要它告诉React应用在构建时所有资源路径如JS、CSS文件的基础URL是什么。对于项目站点它的格式必须是https://username.github.io/repo-name。{ name: my-github-pages-demo, homepage: https://zhangsan.github.io/my-github-pages-demo, // ... 其他原有字段 }然后在scripts部分添加两个新的脚本命令scripts: { start: react-scripts start, build: react-scripts build, test: react-scripts test, eject: react-scripts eject, predeploy: npm run build, deploy: gh-pages -d build }predeploy: 这是一个由npm自动识别的钩子脚本。当我们运行npm run deploy时npm会先自动执行predeploy。这里我们让它执行build确保在部署前先构建出最新的静态文件。deploy: 调用gh-pages工具将build目录即npm run build生成的目录下的所有文件推送到远程仓库的gh-pages分支。3.2 在GitHub上创建仓库并关联现在去GitHub网站创建一个新的仓库。注意这里我们创建的是项目站点所以仓库名可以任意比如就叫my-github-pages-demo不需要是username.github.io。创建时不要初始化README、.gitignore或许可证除非你需要因为我们本地已经有一个项目了。创建成功后按照GitHub页面的提示将我们本地的仓库与远程仓库关联起来# 在本地项目根目录执行 git init git add . git commit -m Initial commit git branch -M main git remote add origin https://github.com/zhangsan/my-github-pages-demo.git git push -u origin main这样我们的源代码就推送到了main分支。3.3 执行部署与开启Pages功能关键的部署步骤来了。在终端运行npm run deploy这个命令会依次执行predeploy-npm run build在本地生成优化后的静态文件到build文件夹。deploy-gh-pages -d buildgh-pages工具会在本地创建一个名为gh-pages的分支如果不存在。将build文件夹的内容复制到这个分支。强制将这个分支推送到远程仓库origin的gh-pages分支。执行成功后终端会输出类似Published的信息。最后一步去GitHub上开启Pages功能。进入你的仓库页面点击Settings-Pages。在Source下拉菜单中选择Deploy from a branch然后在分支下拉菜单中选择gh-pages分支根目录 (/)。点击Save。(此处为描述性文字实际操作请参照GitHub界面)保存后GitHub会开始部署。稍等片刻通常不到一分钟页面上方会显示一个绿色的提示框里面就是你的网站地址格式为https://zhangsan.github.io/my-github-pages-demo。点击它你的React应用就已经在互联网上跑起来了踩坑记录我第一次做的时候部署完访问页面是一片空白控制台报错找不到main.js等资源。这就是因为忘了在package.json里设置homepage字段。没有这个字段React在构建时会假设应用部署在域名的根路径于是资源路径就是/static/js/main.js。但我们的应用实际部署在/my-github-pages-demo/子路径下浏览器就会去https://zhangsan.github.io/static/js/main.js找资源当然找不到。设置了正确的homepage后资源路径会变成/my-github-pages-demo/static/js/main.js问题就解决了。4. 进阶配置自定义域名、HTTPS与自动化工作流基础功能跑通后我们可以让网站变得更专业、更高效。4.1 绑定自定义域名使用username.github.io的域名固然可以但拥有一个自己的域名比如zhangsan.dev显然更酷。操作步骤如下购买域名在任意域名注册商如Namecheap, GoDaddy或国内的阿里云、腾讯云购买你心仪的域名。配置DNS记录在你的域名管理后台添加两条DNS记录记录类型 A主机记录记录值指向GitHub Pages的IP地址。GitHub官方推荐的IP是185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153将这四条IP都添加为A记录可以实现负载均衡。记录类型 CNAME主机记录www记录值指向你的GitHub Pages地址即username.github.io.注意末尾有个点。在GitHub仓库中设置回到仓库的Settings - Pages页面在Custom domain栏输入你的域名如zhangsan.dev然后点击Save。GitHub会自动为你创建一个包含该域名的CNAME文件如果你使用gh-pages分支可能需要手动在项目源码中创建public/CNAME文件并写入域名然后在下次部署时生效。强制HTTPS保存自定义域名后通常等几分钟DNS生效然后这个设置下方会出现一个Enforce HTTPS的复选框勾选它。GitHub会为你免费提供并自动续签SSL证书确保你的网站通过HTTPS安全访问。重要提示如果你使用www子域名如www.zhangsan.dev那么CNAME记录指向username.github.io即可GitHub会自动处理根域名zhangsan.dev的重定向。建议始终开启HTTPS这对搜索引擎排名和用户信任都有好处。4.2 利用GitHub Actions实现CI/CD自动化每次更新代码都要手动运行npm run deploy还是有点麻烦。我们可以利用GitHub Actions实现“推送代码到main分支自动构建并部署到gh-pages”的自动化流水线。在项目根目录创建.github/workflows/deploy.yml文件name: Deploy to GitHub Pages on: push: branches: [ main ] # 当向main分支推送时触发 jobs: build-and-deploy: runs-on: ubuntu-latest # 使用最新的Ubuntu系统作为构建环境 steps: - name: Checkout uses: actions/checkoutv3 # 第一步检出代码 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 # 第二步设置Node.js环境版本按需修改 - name: Install Dependencies run: npm ci # 第三步安装依赖使用ci命令比install更快、更稳定 - name: Build run: npm run build # 第四步执行构建脚本 - name: Deploy uses: peaceiris/actions-gh-pagesv3 # 使用一个专门部署到gh-pages的Action with: github_token: ${{ secrets.GITHUB_TOKEN }} # GitHub自动提供的令牌无需手动配置 publish_dir: ./build # 要发布的目录对应React的build目录将这个文件提交并推送到main分支。之后每次你推送代码GitHub Actions都会自动运行这个工作流拉取代码、安装依赖、构建项目最后将build目录的内容推送到gh-pages分支。你只需要专心写代码部署的事情完全交给自动化。4.3 使用静态网站生成器SSG提升体验对于内容型网站如博客直接手写HTML或用React/ Vue虽然可以但管理文章Markdown文件、生成列表页、标签页等会比较繁琐。这时静态网站生成器SSG是更好的选择。除了GitHub原生支持的Jekyll社区流行的还有Hugo(Go语言): 构建速度极快主题丰富。Hexo(Node.js): 对中文用户友好插件生态庞大。VuePress / VitePress(Vue.js): 非常适合技术文档由Vue.js团队维护。Docusaurus(React): Facebook出品适合大型文档站功能全面。Next.js(React): 虽然以服务端渲染闻名但其静态导出next export功能也能生成完美的静态站点部署到GitHub Pages。这些工具通常都有完善的GitHub Pages部署指南。它们的核心流程与上述React应用类似在本地编写内容Markdown运行生成命令得到静态文件然后将静态文件推送到gh-pages分支或main分支的指定目录。很多工具也提供了与GitHub Actions集成的现成方案。5. 常见问题排查与性能优化指南即使按照步骤操作也可能会遇到一些问题。这里汇总一些常见坑点及其解决方案。5.1 部署后访问404或空白页这是最常见的问题原因和排查步骤如下检查发布源确认仓库Settings - Pages里选择的Branch和文件夹是正确的。如果是项目站点是否选择了gh-pages分支如果是主站是否选择了main分支的根目录检查homepage字段对于Create React App等前端框架务必在package.json中正确配置homepage字段且地址与你的实际访问地址完全一致区分大小写。检查构建输出本地运行npm run build后查看build或dist目录下是否有index.html文件以及其中的资源引用路径是否正确。可以用一个本地HTTP服务器如npx serve build测试一下构建产物本身是否能正常运行。检查仓库内容直接访问你的gh-pages分支如https://github.com/zhangsan/my-github-pages-demo/tree/gh-pages看看里面是否有网站文件。清除浏览器缓存有时是浏览器缓存了旧的错误页面尝试强制刷新CtrlF5或使用隐身模式访问。等待缓存刷新GitHub的CDN可能有延迟部署后等待几分钟再访问。5.2 自定义域名不生效或HTTPS错误DNS生效延迟DNS更改全球生效可能需要几小时到48小时请耐心等待。可以使用dig或nslookup命令检查你的域名是否已解析到GitHub的IP。CNAME文件冲突如果你同时使用了gh-pages分支和自定义域名确保你的CNAME文件在构建后的目录中。对于React可以将其放在public/目录下它会被复制到构建根目录。HTTPS无法开启确保自定义域名已正确保存且DNS已生效。有时需要先通过HTTP访问一次触发GitHub的证书申请流程过一段时间后才能开启HTTPS。如果一直无法开启检查域名DNS设置中是否有冲突的CAA记录。5.3 图片、字体等资源加载失败这通常是由于路径问题。在CSS或JS中引用资源时请使用相对路径或绝对路径基于homepage。错误示例在CSS中:background: url(/images/bg.jpg);这会在根域名下查找对于项目站点会出错。正确示例相对路径:background: url(./images/bg.jpg);或background: url(images/bg.jpg);在React中可以使用process.env.PUBLIC_URL这个环境变量它指向package.json中homepage设置的路径。例如img src{${process.env.PUBLIC_URL}/logo.png} altLogo /5.4 网站访问速度优化GitHub Pages本身已经接入了快速的CDN但我们还可以从以下几个方面让网站更快优化静态资源图片使用现代格式WebP/AVIF通过工具如Squoosh, ImageOptim压缩图片体积。对于图标优先使用SVG格式。代码确保构建工具如Webpack, Vite已开启代码压缩Minify、Tree Shaking等优化选项。利用浏览器缓存虽然不能直接配置服务器缓存头但可以通过在资源文件名中引入哈希值如main.abc123.js来实现“永不过期”的缓存策略。现代前端构建工具默认都会这样做。减少第三方依赖谨慎引入大型的JavaScript库或字体文件它们会显著增加首屏加载时间。考虑更快的替代方案如果对国内访问速度有极高要求可以了解Vercel、Netlify等同样免费且全球边缘网络性能优秀的平台。它们与GitHub集成同样简单并且在某些地区可能有更快的访问速度。但对于绝大多数项目GitHub Pages的性能已经完全足够。我个人在多个项目中长期使用GitHub Pages它的稳定性、与Git工作流的无缝集成以及完全免费的特性使其成为托管静态内容的不二之选。最关键的是养成清晰的工作模式源码在main网站在gh-pages用自动化工具或工作流连接两者。一旦这个流程跑顺了发布网站就会像提交代码一样自然。