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 才能正常工作。操作步骤进入站点所在的仓库在仓库名称下方点击Settings在 GitHub Pages 区块的Source下拉菜单中选择main用于发布到根子域名或gh-pages用于发布到类似/docs的路径作为发布源点击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.jsmodule.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作为站点部署目录运行git checkout -b source main创建名为source的新分支在仓库设置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目录。仓库中默认的静态资源目录即staticGatsby 构建时会把其中所有文件原样复制到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-pathsPREFIX_PATHStrue gatsby build如果未传入该标志Gatsby 会忽略pathPrefix按根域名托管的方式构建站点。还可以用gatsby serve在本地验证构建产物同样需要带--prefix-paths标志gatsby serve --prefix-paths源码印证在 create-cli.ts 中build命令注册了prefix-paths布尔选项其默认值直接取自环境变量PREFIX_PATHStrue或1均为开启serve命令同样注册了prefix-paths选项默认值逻辑与build一致见 create-cli.ts。底层原理在 get-public-path.ts 中getPublicPath函数只有在prefixPaths为真且设置了assetPrefix或pathPrefix时才会拼接出实际的公共路径它会去除各部分首尾斜杠后用/连接若拼接结果不是合法 URLhttp://、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 topage-2Page 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 仅提供纯静态文件托管。这类站点若需完整特性与更快构建可考虑迁移到支持这些能力的托管平台。小结部署前的自检清单按部署方式确认发布源分支路径部署用gh-pages分支子域名部署用main分支路径部署时在gatsby-config.js中正确设置pathPrefix并在deploy脚本中使用gatsby build --prefix-paths使用gatsby serve --prefix-paths在本地验证构建产物自定义域名部署时不要设置pathPrefix并把CNAME文件放到static目录仓库增长后用gh-pages -f避免发布分支历史无限膨胀。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 才能正常工作。操作步骤进入站点所在的仓库在仓库名称下方点击Settings在 GitHub Pages 区块的Source下拉菜单中选择main用于发布到根子域名或gh-pages用于发布到类似/docs的路径作为发布源点击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.jsmodule.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作为站点部署目录运行git checkout -b source main创建名为source的新分支在仓库设置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目录。仓库中默认的静态资源目录即staticGatsby 构建时会把其中所有文件原样复制到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-pathsPREFIX_PATHStrue gatsby build如果未传入该标志Gatsby 会忽略pathPrefix按根域名托管的方式构建站点。还可以用gatsby serve在本地验证构建产物同样需要带--prefix-paths标志gatsby serve --prefix-paths源码印证在 create-cli.ts 中build命令注册了prefix-paths布尔选项其默认值直接取自环境变量PREFIX_PATHStrue或1均为开启serve命令同样注册了prefix-paths选项默认值逻辑与build一致见 create-cli.ts。底层原理在 get-public-path.ts 中getPublicPath函数只有在prefixPaths为真且设置了assetPrefix或pathPrefix时才会拼接出实际的公共路径它会去除各部分首尾斜杠后用/连接若拼接结果不是合法 URLhttp://、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 topage-2Page 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 仅提供纯静态文件托管。这类站点若需完整特性与更快构建可考虑迁移到支持这些能力的托管平台。小结部署前的自检清单按部署方式确认发布源分支路径部署用gh-pages分支子域名部署用main分支路径部署时在gatsby-config.js中正确设置pathPrefix并在deploy脚本中使用gatsby build --prefix-paths使用gatsby serve --prefix-paths在本地验证构建产物自定义域名部署时不要设置pathPrefix并把CNAME文件放到static目录仓库增长后用gh-pages -f避免发布分支历史无限膨胀。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
