企业官网建设流程全解析

Gatsby 路径前缀（pathPrefix）完整指南：从 gatsby-config 配置到构建、本地预览与链接处理

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

导读

很多站点并非部署在域名的根路径（/）下，而是位于某个子目录，例如博客部署在example.com/blog/，或站点托管在 GitHub Pages 的username.github.io/my-gatsby-site/。此时页面内的所有链接（/my-sweet-blog-post/）都需要被改写为带前缀的形式（/blog/my-sweet-blog-post），JavaScript、CSS、图片等静态资源引用也必须同步加上前缀，站点才能在子目录下正常工作。本指南基于 Gatsby 官方文档 path-prefix.md 展开，结合当前仓库中gatsby-link、webpack.config.js、serve.ts等源码实现，完整讲解如何通过pathPrefix配置、--prefix-paths构建标志、gatsby serve本地验证以及Link/navigate/withPrefix等 API 优雅地实现子目录部署，并介绍它与assetPrefix的协同方式。读完本文，你将能独立完成一个"带路径前缀"的 Gatsby 站点的配置、构建、预览与迁移全过程。

什么是路径前缀：为什么需要它

许多应用并不托管在域名的根路径/上。常见的场景包括：

• 博客站点部署在example.com/blog/，所有页面路径都应以/blog开头；
• GitHub Pages 项目页托管在example.github.io/my-gatsby-site/，仓库名即为路径前缀；
• 同一域名下多个应用共存的子目录部署。

在这种场景下，站点内每个内部链接都必须加上前缀：链接/my-sweet-blog-post/应被改写为/blog/my-sweet-blog-post。与此同时，JavaScript、CSS、图片及其他静态资源的引用也需要同样的前缀，否则浏览器在子目录下请求资源时会 404，站点功能将无法正常运行。

Gatsby 的路径前缀特性解决的正是在"非根路径托管"下，页面链接与静态资源引用同步改写的问题。开启该特性是两步式流程：先在gatsby-config中声明pathPrefix，再在构建/预览时显式传入--prefix-paths标志（或PREFIX_PATHS环境变量）。

从源码结构看，pathPrefix属于 gatsby-config.js 顶层配置项 之一；完整的前置要求是先有一个可运行的 Gatsby 项目（参见 快速开始）。

第一步：在 gatsby-config 中添加 pathPrefix

首先在项目根目录的gatsby-config.js中声明pathPrefix值。例如博客托管在/blog子目录：

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

配置要点：

• pathPrefix必须以/开头（如/blog、/prefix），这是约定俗成的写法；
• 它只是一个声明，仅此配置并不会生效——还需要在构建时显式开启前缀处理（见下一步）；
• 仓库中的官方示例 examples/using-path-prefix/gatsby-config.js 即采用同样的写法：

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

该示例站点还配套了 examples/using-path-prefix/src/pages/index.js、a.js、b.js、c.js四个页面，其中首页通过<Link to="/a/">等组件链接到各子页面，正是验证路径前缀行为的完整测试样例。

第二步：使用 --prefix-paths 标志构建

在gatsby-config声明pathPrefix之后，还需要用带--prefix-paths标志（或PREFIX_PATHS环境变量）的方式构建应用：

gatsby build --prefix-paths

等价的环境变量方式：

PREFIX_PATHS=true gatsby build

如果不传该标志，Gatsby 会直接忽略pathPrefix，按站点托管在根域名来构建——所有资源与链接都不会带前缀。这一点在 asset-prefix.md 中也有明确表述："If this flag or env variable is not specified, the build will ignore this option"。

从源码层面看，--prefix-paths标志最终被解析为程序参数program.prefixPaths，其类型定义见 packages/gatsby/src/commands/types.ts，属于IProgram的可选布尔字段：

export interface IProgram { ... prefixPaths?: boolean ... }

前缀如何注入构建产物

真正决定"资源引用如何改写"的核心逻辑位于 packages/gatsby/src/utils/get-public-path.ts：

export const getPublicPath = ({ assetPrefix, pathPrefix, prefixPaths, }: { assetPrefix?: string pathPrefix?: string prefixPaths?: boolean }): string => { if (prefixPaths && (assetPrefix || pathPrefix)) { const normalized = [assetPrefix, pathPrefix] .filter((part): part is string => (part ? part.length > 0 : false)) .map(part => trimSlashes(part)) .join(`/`) return isURL(normalized) ? normalized : `/${normalized}` } return `` }

可以看到getPublicPath做了两件事：串联assetPrefix与pathPrefix（都去掉首尾斜杠后用/连接），以及判断拼接结果是否为完整 URL（http://、https://、//开头则原样返回）。这一行为由单元测试 packages/gatsby/src/utils/tests/get-public-path.ts 覆盖，包括"返回 assetPrefix""返回 pathPrefix""连接两者""处理相对 assetPrefix""处理 CDN 型 URL assetPrefix""处理双斜杠""处理尾部斜杠"等场景。

随后在 packages/gatsby/src/utils/webpack.config.js 中，webpack 配置从 Redux store 中读取assetPrefix与pathPrefix，并调用getPublicPath计算构建公共路径：

const { assetPrefix, pathPrefix, trailingSlash } = store.getState().config const publicPath = getPublicPath({ assetPrefix, pathPrefix, ...program })

同一文件中还向编译产物注入两个全局常量（webpack.config.js）：

__BASE_PATH__: JSON.stringify(program.prefixPaths ? pathPrefix : ``), __PATH_PREFIX__: JSON.stringify(program.prefixPaths ? publicPath : ``),

• __BASE_PATH__等于配置中的原始pathPrefix（如/blog）；
• __PATH_PREFIX__等于getPublicPath的计算结果，在同时使用assetPrefix时它是<assetPrefix>/<pathPrefix>的组合值。

这两个全局常量正是运行时Link、withPrefix等 API 自动加前缀的数据来源。若未传--prefix-paths，两者均为空字符串，前缀逻辑自然失效——这与文档所述"Gatsby 会忽略你的 pathPrefix"完全吻合。

第三步：用 gatsby serve 本地验证

构建完成后，可以使用gatsby serve在本地验证带前缀的构建产物。服务时同样需要传--prefix-paths标志：

gatsby serve --prefix-paths

与build一致，如果不传该标志，Gatsby 会忽略pathPrefix，本地预览将无法正确模拟子目录部署。

从源码看，gatsby serve的实现在 packages/gatsby/src/commands/serve.ts 中。它从配置模块读取pathPrefix与trailingSlash，并根据prefixPaths是否开启来决定挂载前缀：

const { pathPrefix: configPathPrefix, trailingSlash } = config || {} const pathPrefix = prefixPaths && configPathPrefix ? configPathPrefix : `/`

随后通过app.use(pathPrefix, router)将整个静态资源路由挂载到带前缀的路径上（serve.ts）。也就是说：传了--prefix-paths时，localhost:9000/blog/才能正确访问站点；否则资源仍挂在根路径。

官方示例 examples/using-path-prefix/README.md 给出了完整的本地验证流程：

gatsby build --prefix-paths cd public mkdir prefix mv * prefix # This will cause an error but you can ignore it cd .. gatsby serve # Open the served site at localhost:9000/prefix/

即将public目录下所有构建产物移入prefix子目录以模拟子目录托管，再通过gatsby serve访问localhost:9000/prefix/。注意：在真实托管平台（如 GitHub Pages、Nginx 等）上部署时，无需手动搬移文件，平台本身就会把站点挂载在子目录下——上面的mkdir/mv只是为了本地模拟。

对于 GitHub Pages 场景，how-gatsby-works-with-github-pages.md 给出了与本文完全一致的组合：仓库站点（username.github.io/reponame/）需要pathPrefix: "/reponame"加--prefix-paths构建，并用gh-pages -d public发布；而自定义域名或username.github.io形式的用户页不要添加pathPrefix，否则会破坏站内导航。

站内链接处理：Link、navigate 与 withPrefix

路径前缀最大的便利在于：你不需要在自己的代码里硬编码前缀。Gatsby 提供了一系列开箱即用的 API 自动完成前缀拼接。

Link 组件自动加前缀

Link组件内置了路径前缀处理能力。假设你想链接到/page-2，而实际链接将是带前缀的/blog/page-2——使用Link时无需硬编码前缀，路径会自动被加上gatsby-config.js中声明的pathPrefix值。如果日后你迁移到不使用路径前缀的部署方式，这些链接依然无缝工作。

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

navigate 动态导航

编程式/动态导航同样支持前缀。Gatsby 暴露的navigate辅助函数也会自动处理路径前缀：

import React from "react" import { navigate } from "gatsby" import Layout from "../components/layout" export default function Index() { return ( <Layout> {/* Note: this is an intentionally contrived example, but you get the idea! */} {/* highlight-next-line */} <button onClick={() => navigate("/page-2")}> Go to page 2, dynamically </button> </Layout> ) }

源码实现：前缀从何而来

Link与navigate的前缀处理统一收敛在 packages/gatsby-link/src 中。Link组件渲染时调用rewriteLinkPath将to改写为带前缀的路径（packages/gatsby-link/src/index.js）；navigate同样先改写路径再交给window.___navigate（index.js）。

前缀取值来自 packages/gatsby-link/src/prefix-helpers.js：

export const getGlobalBasePrefix = () => process.env.NODE_ENV !== `production` ? typeof __BASE_PATH__ !== `undefined` ? __BASE_PATH__ : undefined : __BASE_PATH__ export const getGlobalPathPrefix = () => process.env.NODE_ENV !== `production` ? typeof __PATH_PREFIX__ !== `undefined` ? __PATH_PREFIX__ : undefined : __PATH_PREFIX__ export function withPrefix(path, prefix = getGlobalBasePrefix()) { if (!isLocalLink(path)) { return path } if (path.startsWith(`./`) || path.startsWith(`../`)) { return path } const base = prefix ?? getGlobalPathPrefix() ?? `/` return `${base?.endsWith(`/`) ? base.slice(0, -1) : base}${ path.startsWith(`/`) ? path : `/${path}` }` }

要点：

• 非本地链接（外部 URL）与相对链接（./、../开头）不会被改写；
• 优先使用__BASE_PATH__（即配置中的pathPrefix），其次回退到__PATH_PREFIX__（可能含assetPrefix组合），最后回退到/；
• 拼接时正确处理首尾斜杠，避免出现双斜杠。

手动路径用 withPrefix

对于你手动拼接的路径名（例如判断当前是否首页、构造资源 URL 等），有专门的辅助函数withPrefix，它会在生产环境为路径加上前缀，而在开发环境不加（开发模式下路径本身无需前缀）：

import { withPrefix } from "gatsby" const IndexLayout = ({ children, location }) => { const isHomepage = location.pathname === withPrefix("/") return ( <div> <h1>Welcome {isHomepage ? "home" : "aboard"}!</h1> {children} </div> ) }

withPrefix的实现同样位于 packages/gatsby-link/src/prefix-helpers.js，其行为被单元测试覆盖于 packages/gatsby-link/src/tests/index.js：当设置了global.__PATH_PREFIX__时，withPrefix(to)返回${__PATH_PREFIX__}${to}。withPrefix还可与getGlobalPathPrefix()结合衍生出withAssetPrefix（见 packages/gatsby-link/src/index.js），用于为资源路径加前缀。

与其他特性协同：assetPrefix 与 basePath

配合 assetPrefix 使用

assetPrefix可以视为与pathPrefix半相关的特性：它允许将非 HTML 资源（图片、JavaScript 等）托管到独立的域名，例如 CDN。两者可以无缝协同：用--prefix-paths构建站点，就能实现"核心功能位于路径前缀下，静态资源托管在 CDN"的部署形态。

关键行为：如果使用assetPrefix，你的pathPrefix会变为<assetPrefix>/<pathPrefix>。这一点正是 get-public-path.ts 中join('/')拼接逻辑的体现，也是__PATH_PREFIX__（组合值）与__BASE_PATH__（原始pathPrefix）分开存在的原因。

需要原始 pathPrefix 时使用 basePath

如果你在 Node API 钩子（如onPostBuild）中需要访问与gatsby-config中一致的、未经assetPrefix组合的pathPrefix，请使用 basePath 参数：

exports.onPostBuild = ({ reporter, basePath, pathPrefix }) => { reporter.info( `Site was built with basePath: ${basePath} & pathPrefix: ${pathPrefix}` ) }

补充：createRedirect 也会自动加前缀

路径前缀不仅作用于链接与资源，还作用于重定向。在 packages/gatsby/src/redux/actions/public.js 中，createRedirect的fromPath与toPath会在store.getState().program.prefixPaths为真时自动调用maybeAddPathPrefix加上config.pathPrefix：

let pathPrefix = `` if (store.getState().program.prefixPaths) { pathPrefix = store.getState().config.pathPrefix }

其中maybeAddPathPrefix（public.js）会跳过已有协议或//开头的绝对链接，只为本地路径补前缀：

const maybeAddPathPrefix = (path, pathPrefix) => { const parsed = url.parse(path) const isRelativeProtocol = path.startsWith(`//`) return `${ parsed.protocol != null || isRelativeProtocol ? `` : pathPrefix }${path}` }

这意味着使用createRedirect时同样无需手动书写前缀，Gatsby 会依据prefixPaths开关自动处理。

完整操作流程回顾

1. 声明前缀：在 gatsby-config.js 中添加pathPrefix: "/blog"（以/开头）；
2. 带标志构建：运行gatsby build --prefix-paths或PREFIX_PATHS=true gatsby build，缺省时前缀被忽略；
3. 本地验证：运行gatsby serve --prefix-paths，可结合官方示例 examples/using-path-prefix/README.md 的mkdir/mv流程模拟子目录托管；
4. 站内导航：统一使用Link、navigate，手动拼接路径时使用withPrefix，不要硬编码前缀；
5. 上线部署：将public产物部署到子目录（如 GitHub Pages 仓库站点username.github.io/reponame/），平台负责把站点挂在对应路径下。

前提与限制说明：

• 以上行为均以当前仓库（Gatsby 5.x 时代代码）的实现为准；pathPrefix仅在build/serve传入--prefix-paths时生效；
• 自定义域名部署（站点在根路径）时不要设置pathPrefix，否则会导致导航与资源路径错乱；
• 本地开发（gatsby develop）通常不需要前缀，withPrefix在开发环境也不会加前缀，原因在于开发服务器直接以根路径服务，无需模拟子目录。

通过这套机制，你可以放心地把 Gatsby 站点部署到任意子目录，且日后即使迁移回根路径托管，只需移除配置并重新构建即可，所有通过官方 API 书写的链接无需任何改动。

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