配置重定向 | Fern Documentation

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

设置重定向

在 docs.yml 中使用精确路径或正则表达式模式进行配置，可指向内部路径或外部 URL。

如果您的文档托管在子路径上（如 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*"

带有星号 (*) 后缀的参数匹配零个或多个路径段，捕获 URL 中后面的所有内容。在重定向整个文件夹结构时使用此功能以保留嵌套路径。

重定向按从上到下的顺序进行评估，第一个匹配的规则生效：

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*"

将更宽泛的模式放在更具体的模式之前会阻止具体规则匹配。

属性

source

stringRequired

您要重定向的相对路径（例如，/old-path）。必须是相对路径，而不是绝对 URL。不能包含搜索参数（例如，?key=value）。

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 规则调整严重级别。