Gatsby 部署到 GitHub Pages 完整指南：pathPrefix 配置、gh-pages 发布与自定义域名

Gatsby 部署到 GitHub Pages 完整指南：pathPrefix 配置、gh-pages 发布与自定义域名

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

导读

GitHub Pages 是 GitHub 提供的静态站点托管服务，可直接从仓库中发布网站。Gatsby 站点只需对代码库和仓库设置做少量配置，就能托管到 GitHub Pages。本文以仓库中的 how-gatsby-works-with-github-pages.md 为主线，结合 path-prefix.md 与packages/gatsby、packages/gatsby-cli、packages/gatsby-link等源码实现，系统讲解三种发布方式（路径部署、子域名部署、自定义域名部署）的完整流程，并深入剖析--prefix-paths标志、pathPrefix配置的底层原理，读完即可把 Gatsby 站点稳定发布到 GitHub Pages。

发布方式总览

你可以通过以下几种方式将 Gatsby 站点发布到 GitHub Pages：

• 路径部署：发布到类似username.github.io/reponame/或/docs的路径下；
• 子域名部署：发布到基于用户名或组织名的子域名，如username.github.io或orgname.github.io；
• 根域名 + 自定义域名：发布到根子域名username.github.io，再配置自定义域名。

前置条件

开始之前请确保：

• 已有一个 Gatsby 项目。如果还没有，可参考 Quick Start 快速创建一个；
• 拥有一个 GitHub 账号。

通用配置步骤

配置 GitHub Pages 发布源分支

必须先在 GitHub 仓库设置中选定将要部署的分支，GitHub Pages 才能正常工作。操作步骤：

1. 进入站点所在的仓库；
2. 在仓库名称下方点击"Settings"；
3. 在 GitHub Pages 区块的"Source"下拉菜单中选择main（用于发布到根子域名）或gh-pages（用于发布到类似/docs的路径）作为发布源；
4. 点击"Save"保存。

注意：要选择main或gh-pages作为发布源，仓库中必须已存在该分支。如果还没有main或gh-pages分支，可以先创建它们，再回到发布源设置中更改选项。

安装gh-pages包

将 Gatsby 应用推送到 GitHub Pages 的最佳方式是使用名为gh-pages的 npm 包，作为开发依赖安装：

npm install gh-pages --save-dev

使用 deploy 脚本

在package.json的"scripts"区块添加自定义的deploy脚本，可以更方便地发布站点。具体配置方式取决于你选择的发布方式，详见下文各小节。

三种部署方式详解

方式一：部署到带 pathPrefix 的路径

对于部署在类似username.github.io/reponame/路径下的站点，需要使用--prefix-paths标志，因为网站最终会位于username.github.io/reponame/这样的文件夹内。首先需要把/reponame作为 path prefix 添加到gatsby-config.js：

module.exports = { pathPrefix: "/reponame", }

然后在仓库代码库的package.json中添加deploy脚本：

{ "scripts": { "deploy": "gatsby build --prefix-paths && gh-pages -d public" } }

在main分支上运行npm run deploy后，public文件夹的全部内容会被推送到仓库的gh-pages分支。请确保仓库设置中已将gh-pages分支设为发布源。

⚠️ 随着仓库增长和提交增多，gh-pages分支也会越来越大，可能拖慢 clone 等操作并增加磁盘占用。可以在gh-pages命令中使用-f选项，避免保留 GitHub Pages 分支的历史记录。

提示：仓库中的 using-path-prefix 示例展示了pathPrefix的实际配置方式，其gatsby-config.js中设置了pathPrefix: '/prefix'，可作为参照。

方式二：部署到 github.io 子域名

对于名为username.github.io的仓库，不需要指定pathPrefix，站点需要推送到main分支。

⚠️ 请注意：GitHub Pages 强制要求用户/组织页面部署到main分支。因此如果你用main做开发分支，需要采取以下措施之一：

• 将默认分支从main改为其他分支，仅把main作为站点部署目录：
  1. 运行git checkout -b source main创建名为source的新分支；
  2. 在仓库设置（"Branches" 菜单项）中把默认分支从main改为source。
• 注意：GitHub Pages 允许使用任意分支进行部署，这意味着你不一定非要更改默认分支。
• 为源代码单独建一个仓库（即username.github.io只用于部署，不真正跟踪源代码）。如果走这条路，需要在下面的gh-pages命令中额外增加--repo <repo>选项（支持 https 和 git 两种 URL）。

对应package.json中的 deploy 脚本：

{ "scripts": { "deploy": "gatsby build && gh-pages -d public -b main" } }

如果部署到非main的分支，请把 deploy 脚本中的分支名替换成你的部署分支名称。

运行npm run deploy后，即可在username.github.io看到你的网站。

方式三：部署到根子域名并使用自定义域名

如果使用自定义域名，不要添加pathPrefix，否则会破坏站点内的导航。只有在站点不在域名根路径（如仓库站点）时才需要路径前缀。

注意：别忘了把 CNAME 文件放入static目录。仓库中默认的静态资源目录即static，Gatsby 构建时会把其中所有文件原样复制到public输出目录。

使用 GitHub Actions

你也可以使用 GitHub Actions 将 Gatsby 站点推送到 GitHub Pages，可参考 Gatsby Publish 相关 Action 了解具体用法。本质上与本地deploy脚本一致：先gatsby build构建出public目录，再将其内容推送到发布分支。

深入理解：pathPrefix 与 --prefix-paths 的工作原理

路径部署方式的核心在于--prefix-paths标志和pathPrefix配置，二者配合才能让站点的所有链接带上正确的路径前缀。以下结合源码分析其底层机制。

gatsby-config 中的 pathPrefix

首先需要在gatsby-config.js中设置pathPrefix值。它定义了站点所有路径的统一前缀，例如部署在example.com/blog/下的站点需要把链接/my-sweet-blog-post/重写为/blog/my-sweet-blog-post，同时 JavaScript、CSS、图片等静态资源的链接也要加上同样的前缀，站点才能在带前缀的路径下正常运行：

module.exports = { pathPrefix: `/blog`, }

构建与本地验证：--prefix-paths 标志

配置好pathPrefix后，最后一步是用--prefix-paths标志或PREFIX_PATHS环境变量构建应用：

gatsby build --prefix-paths

PREFIX_PATHS=true gatsby build

如果未传入该标志，Gatsby 会忽略pathPrefix，按根域名托管的方式构建站点。

还可以用gatsby serve在本地验证构建产物，同样需要带--prefix-paths标志：

gatsby serve --prefix-paths

源码印证：在 create-cli.ts 中，build命令注册了prefix-paths布尔选项，其默认值直接取自环境变量PREFIX_PATHS（true或1均为开启）；serve命令同样注册了prefix-paths选项，默认值逻辑与build一致（见 create-cli.ts）。

底层原理：在 get-public-path.ts 中，getPublicPath函数只有在prefixPaths为真且设置了assetPrefix或pathPrefix时才会拼接出实际的公共路径：它会去除各部分首尾斜杠后用/连接，若拼接结果不是合法 URL（http://、https://、//开头）则补上前导/，最终得到类似/reponame的publicPath。这就是为什么--prefix-paths与pathPrefix必须同时生效——前缀路径只会在构建产物中体现。

应用内链接自动带前缀

Gatsby 提供了开箱即用的 API 和库来无缝使用该特性。Link组件内置了路径前缀处理：例如链接目标是/page-2，而实际链接会被加上前缀变成/blog/page-2，你无需把前缀硬编码进链接。使用 Gatsby 的Link组件后，路径会自动拼接gatsby-config.js中赋值的pathPrefix。如果之后迁移到不使用路径前缀的部署方式，这些链接仍然能正常工作。

import React from "react" import { Link } from "gatsby" import Layout from "../components/layout" function Index() { return ( <Layout> <Link to="page-2">Page 2</Link> </Layout> ) }

程序化/动态导航同样支持：Gatsby 导出的navigate助手函数也会自动处理路径前缀：

import React from "react" import { navigate } from "gatsby" import Layout from "../components/layout" export default function Index() { return ( <Layout> <button onClick={() => navigate("/page-2")}> Go to page 2, dynamically </button> </Layout> ) }

源码印证：在 gatsby-link 的测试 中，Link组件会把pathPrefix拼接到目标路径前（包括带尾斜杠的pathPrefix也能正确处理），并对外部链接忽略前缀；withPrefix助手会把pathPrefix作为路径前缀返回（见 index.js 测试）。

手动拼接路径：withPrefix

对于手动构造的路径名，可以借助withPrefix辅助函数：它在生产环境为路径加上前缀，而在开发环境不添加（因为开发时路径不需要前缀）。该函数定义于 prefix-helpers.js，并从 gatsby-link 的入口 对外导出。

与 assetPrefix 的关系

assetPrefix特性与路径前缀半相关：它允许把资源（非 HTML 文件，如图片、JavaScript 等）托管到独立域名（例如 CDN）。它与pathPrefix可以无缝配合——用--prefix-paths构建应用后，即可实现"资源托管在 CDN、核心功能位于路径前缀之下"的架构。若同时使用assetPrefix，则pathPrefix会变为<assetPrefix>/<pathPrefix>；如果需要访问gatsby-config中原本的pathPrefix，可考虑使用basePath。

局限性说明

GitHub Pages 不支持 SSR（服务端渲染）、DSG（延迟静态生成）或 Image CDN 等高级特性，因为这些能力依赖运行时服务器或云端的按需处理，而 GitHub Pages 仅提供纯静态文件托管。这类站点若需完整特性与更快构建，可考虑迁移到支持这些能力的托管平台。

小结：部署前的自检清单

1. 按部署方式确认发布源分支：路径部署用gh-pages分支，子域名部署用main分支；
2. 路径部署时在gatsby-config.js中正确设置pathPrefix，并在deploy脚本中使用gatsby build --prefix-paths；
3. 使用gatsby serve --prefix-paths在本地验证构建产物；
4. 自定义域名部署时不要设置pathPrefix，并把CNAME文件放到static目录；
5. 仓库增长后，用gh-pages -f避免发布分支历史无限膨胀。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby