> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI2ZGJjZjRhZi0yZjM1LTRkOTktYTA3Ny1lOGNjMmQzMWU0ZDIiLCJleHAiOjE3NzgyOTEzNTYsImlhdCI6MTc3ODI5MTA1Nn0.uMeP2gEHdc9zEWklI8K_vV1wVMeh7GEOd-4MA0203Ms
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 配置重定向

## 重定向

The `redirects` object allows you to redirect traffic from one path to another. You can redirect exact paths or use dynamic patterns with [`regex`](https://www.npmjs.com/package/path-to-regexp) parameters like `:slug` to handle bulk redirects. You can redirect to internal paths within your site or external URLs.

If your docs are hosted on a subpath (like `buildwithfern.com/learn`), include the subpath in both the source and destination paths.

<CodeBlock title="docs.yml">
  ```yml
  redirects:
    # Exact path redirects
    - source: "/old-path"
      destination: "/new-path"
    - source: "/old-folder/path"
      destination: "/new-folder/path"
    - source: "/old-folder/path"
      destination: "https://www.example.com/fern" # External destination
    - source: "/temporary-redirect"
      destination: "/new-location"
      permanent: false # Use 307 (temporary) instead of 308 (permanent)
      
    # Regex-based redirects
    - source: "/old-folder/:slug" # Matches single segments: /old-folder/foo
      destination: "/new-folder/:slug"   
    - source: "/old-folder/:slug*" # Matches multiple segments: /old-folder/foo/bar/baz 
      destination: "/new-folder/:slug*"  
  ```
</CodeBlock>

<Info>
  Parameters suffixed with an asterisk (`*`) match zero or more path segments, capturing everything that follows in the URL. Use this when redirecting entire folder structures while preserving nested paths.
</Info>

<ParamField path="source" type="string" required={true}>
  The relative path you want to redirect from (e.g., `/old-path`). Must be a relative path, not an absolute URL. Must not include search parameters (e.g., `?key=value`).
</ParamField>

<ParamField path="destination" type="string" required={true}>
  The path you want to route to. Can be an internal path (`/new-path`) or an external URL (`https://example.com`). External URLs must include the full address, including `https`.
</ParamField>

<ParamField path="permanent" type="boolean" required={false} default="true">
  By default, uses the 308 status code to instructs clients and search engines to cache the redirect forever. Set to `false` only if you need a temporary redirect using the 307 status code, which won't be cached.
</ParamField>

### Best practices

For optimal site performance, only add redirects when necessary. Avoid using redirects for behavior that Fern already handles automatically, such as 404 handling and version routing.

<AccordionGroup>
  <Accordion title="404 handling">
    Don't create redirects to send broken links to your homepage:

    ```yaml title="docs.yml"
    redirects:
      - source: /docs/event-notifications
        destination: / # Don't do this
    ```

    Instead, [enable automatic homepage redirects in your `docs.yml`](/docs/configuration/site-level-settings#settings-configuration) to send broken links to your homepage rather than showing a 404 page:

    ```yaml title="docs.yml"
    settings:
      hide-404-page: true
    ```
  </Accordion>

  <Accordion title="Versioning and redirects">
    If you have [versions](/docs/configuration/versions) configured, your default version uses unversioned paths (`/docs/getting-started`), while other versions use versioned paths (`/docs/getting-started/v2`). Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs.

    Avoid redirecting from unversioned to versioned URLs:

    ```yaml title="docs.yml"
    redirects:
      - source: /docs/event-notifications
        destination: /docs/event-notifications/v2 # Don't do this
    ```

    Manually overriding the default versioning behavior can lead to unexpected redirect patterns.

    If you frequently need to redirect from the default version to another version, consider changing which version is set as default in your versions configuration.
  </Accordion>
</AccordionGroup>

<Tip>
  要向侧边栏导航添加外部链接，请参见[导航](/learn/docs/configuration/navigation#links)。
</Tip>

## 常见错误

以下错误由 `fern check` 和 `fern generate --docs` 发现。

### Page "X" was moved from "/old" to "/new". The old URL will return 404 without a redirect.

页面的[slug](/learn/docs/seo/configuring-slugs)相对于文档的上一个[已发布版本](/learn/docs/preview-publish/publishing-your-docs)发生了更改。在 `docs.yml` 中添加[重定向](/learn/docs/configuration/site-level-settings#redirects-configuration)，以便现有链接继续有效：

```yaml title="docs.yml"
redirects:
  - source: /old
    destination: /new
```

### Page "X" was removed. The previously published URL "/old" will return 404 without a redirect.

[已发布的页面](/learn/docs/preview-publish/publishing-your-docs)在[导航](/learn/docs/configuration/navigation)中不再存在。添加[重定向](/learn/docs/configuration/site-level-settings#redirects-configuration)到另一个相关页面，以避免破坏传入链接：

```yaml title="docs.yml"
redirects:
  - source: /old
    destination: /new-home
```

### Redirect from "/path" to "/path" creates an infinite loop (source equals destination).

[重定向](/learn/docs/configuration/site-level-settings#redirects-configuration)指向自身——对 `/path` 的请求会被重定向到 `/path`，如此无限循环。要么删除重定向（如果 `/path` 是一个有效页面），要么将 `destination` 指向不同的 URL。

```yaml title="docs.yml"
redirects:
  - source: /path
    destination: /new-path  # 必须与 `source` 不同
```

### Circular redirect chain detected: /a → /b → /a

两个或更多[重定向](/learn/docs/configuration/site-level-settings#redirects-configuration)形成循环：`/a` 重定向到 `/b`，而 `/b` 重定向回 `/a`（直接或通过更多跳转）。浏览器会在它们之间无限反弹。将链中的每个 `source` 直接指向最终目的地，这样就没有 `destination` 本身是另一个 `source`。

```yaml title="docs.yml"
redirects:
  - source: /a
    destination: /c  # 跳过 `/b`，直接到达最终页面
  - source: /b
    destination: /c
```