配置重定向 | Fern Documentation

重定向将旧 URL 映射到新 URL，以便在页面移动、更改 slug 或被删除时，入站链接和搜索排名得以保留。

设置重定向

在 docs.yml 中配置重定向，可指向内部路径或外部 URL。当单个 URL 发生变更时使用精确路径；当某个路径及其下层内容一并变更时，请使用模式：精确的 source 只匹配该 URL 本身，不匹配其下层路径，因此 /old-folder 不会影响 /old-folder/page。

如果您的文档托管在子路径上（如 buildwithfern.com/learn），请在源路径和目标路径中都包含该子路径。

docs.yml

1 redirects:
2   # 精确路径重定向
3   - source: "/old-path"
4     destination: "/new-path"
5   - source: "/old-folder/path"
6     destination: "/new-folder/path"
7   - source: "/old-folder/path"
8     destination: "https://www.example.com/fern" # 外部目标
9   - source: "/temporary-redirect"
10     destination: "/new-location"
11     permanent: false # 使用 307（临时）而不是 308（永久）
12 
13   # 基于模式的重定向
14   - source: "/old-folder/:slug" # 匹配单个段：/old-folder/foo
15     destination: "/new-folder/:slug"
16   - source: "/old-folder/:slug*" # 匹配多个段：/old-folder/foo/bar/baz
17     destination: "/new-folder/:slug*"
18   - source: "/old-:slug(.*)" # 匹配段中间的内容：/old-guides/setup
19     destination: "/new-:slug(.*)"

模式语法

参数是以 : 为前缀的名称。每个参数捕获传入 URL 的一部分，并在 destination 中以相同的名称回填。

模式	示例 `source`	匹配
`:slug`	`/plants/:slug`	匹配 `/plants/monstera`，不匹配 `/plants/indoor/monstera`
`:slug*`	`/plants/:slug*`	匹配 `/plants` 和 `/plants/indoor/monstera`
`:slug+`	`/plants/:slug+`	匹配 `/plants/indoor/monstera`，不匹配 `/plants`
`:slug(regex)`	`/plants-:slug(.*)`	匹配 `/plants-indoor/monstera`
`(regex)`	`/plants/(\d+)`	匹配 `/plants/42`

未命名的分组没有可回填的名称，因此在 destination 中以 :0 出现。

正则表达式是从段中间开始匹配的唯一方式，因为 :slug、:slug* 和 :slug+ 都必须紧跟在 / 之后。它同样可以收窄参数，而不只是放宽参数：/v:version(\d+)/plants/:slug* 匹配 /v2/plants/monstera/care，并将 version 捕获为 2。

必须在 destination 中重复该正则表达式。在 source 中写成 :slug(.*) 的参数，在 destination 中也要保持 :slug(.*)，因为不带正则表达式的 :slug 无法容纳包含 / 的值；省略它会使重定向解析为字面文本 /new-folder/:slug。

不支持可选修饰符 (?)。Fern 会在第一个 ? 处截断每个 source 以去除查询参数，因此 /old-folder/:slug? 会按 /old-folder/:slug 进行匹配。

评估顺序

重定向按从上到下的顺序进行评估，第一个匹配的规则生效，因此请将具体路径放在更宽泛的路径之前：

docs.yml

1 redirects:
2   # 先放具体路径——匹配 /docs/api/billing/overview 等
3   - source: "/docs/api/billing/:slug*"
4     destination: "/docs/reference/billing/:slug*"
5 
6   # 再放宽泛的通配符——匹配 /docs/api/ 下的其他所有内容
7   - source: "/docs/api/:slug*"
8     destination: "/docs/reference/:slug*"

属性

redirects 下的每个条目都接受以下属性。

source

stringRequired

您要重定向的相对路径（例如，/old-path）。必须是相对路径，而不是绝对 URL。不能包含搜索参数（例如，?key=value）。匹配前会对末尾斜杠进行归一化，因此 /old-path/ 和 /old-path 等价。请与所重定向 URL 的大小写保持一致。

destination

stringRequired

您要路由到的路径。可以是内部路径（/new-path）或外部 URL（https://example.com）。外部 URL 必须包含完整地址，包括 https。

permanent

booleanDefaults to true

默认使用 308 状态码指示客户端和搜索引擎永久缓存重定向。只有在需要使用 307 状态码的临时重定向时才设置为 false，这不会被缓存。

何时不应添加重定向

为了获得最佳的站点性能，只在必要时添加重定向。Fern 已经自动处理 404 和版本路由，重复这些行为的重定向反而会起反作用。

404 处理

不要将损坏的链接重定向到您的主页：

docs.yml

1 redirects:
2   - source: /docs/event-notifications
3     destination: / # 不要这样做

相反，在您的 docs.yml 中启用自动主页重定向，将损坏的链接发送到您的主页，而不是显示 404 页面：

docs.yml

1 settings:
2   hide-404-page: true

版本控制

如果您配置了版本，您的默认版本使用无版本路径（/docs/getting-started），而其他版本使用有版本路径（/docs/v2/getting-started）。Fern 通过将损坏的有版本链接重定向到默认版本并管理规范 URL 来自动处理版本路由。

避免从无版本 URL 重定向到有版本 URL：

docs.yml

1 redirects:
2   - source: /docs/event-notifications
3     destination: /docs/v2/event-notifications # 不要这样做

手动覆盖默认版本控制行为可能导致意外的重定向模式。如果您经常需要从默认版本重定向到另一个版本，请在版本配置中更改哪个版本设置为默认版本。

捕获缺失的重定向

missing-redirects 规则由 fern check 运行，它将从您的本地 YAML 构建的导航树与您站点最近发布的状态进行比较，并标记那些之前发布的 URL，这些 URL 现在无法解析且不在 redirects: 条目中。这可以在页面开始为现有入站链接返回 404 错误之前，捕获您已移动或删除的页面。

使用 docs.yml 中的 missing-redirects 规则调整严重级别。