重定向

重定向会将读者从旧 URL 引导到新 URL。在重组文档、重命名页面，或保持之前文档版本中的链接可用时，请使用重定向。

配置

在 docs.json 中添加重定向：

{
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page"
    },
    {
      "source": "/guides/setup",
      "destination": "/getting-started"
    }
  ]
}

重定向类型

精确匹配

重定向特定 URL：

{
  "source": "/api/v1/users",
  "destination": "/api/v2/users"
}

/api/v1/users → /api/v2/users

通配符匹配

使用 * 匹配路径段：

{
  "source": "/blog/*",
  "destination": "/articles/*"
}

/blog/hello-world → /articles/hello-world

前缀匹配

重定向某个前缀下的所有路径：

{
  "source": "/v1/*",
  "destination": "/v2/*"
}

/v1/api/users → /v2/api/users

HTTP 状态码

重定向默认返回 308（永久重定向）。如需其他状态码，请进行设置：

{
  "source": "/old-page",
  "destination": "/new-page",
  "statusCode": 307
}

大多数文档重定向请使用 308。迁移期间的临时移动请使用 307。

常见模式

重组文档

{
  "redirects": [
    { "source": "/setup", "destination": "/getting-started" },
    { "source": "/setup/install", "destination": "/getting-started/installation" },
    { "source": "/setup/config", "destination": "/getting-started/configuration" }
  ]
}

API 版本迁移

{
  "redirects": [
    { "source": "/api/v1/*", "destination": "/api/v2/*" }
  ]
}

外部重定向

{
  "source": "/community",
  "destination": "https://discord.gg/your-server"
}

保留 SEO

对已移动页面使用永久重定向以保持搜索排名：

{
  "redirects": [
    {
      "source": "/tutorials/getting-started-with-api",
      "destination": "/quickstart",
      "statusCode": 301
    }
  ]
}

重定向顺序

重定向按顺序求值。请将具体规则放在通配符规则之前：

{
  "redirects": [
    { "source": "/api/v1/special-endpoint", "destination": "/api/special" },
    { "source": "/api/v1/*", "destination": "/api/v2/*" }
  ]
}

第一条匹配的规则生效。

限制

• 重定向仅适用于文档路径
• 查询参数会自动保留
• 哈希片段会自动保留
• 每个项目最多 1000 条重定向

测试重定向

1. 部署您的更改
2. 直接访问旧 URL
3. 确认跳转到新的目标地址
4. 在浏览器开发者工具中检查 HTTP 状态码

# Check redirect with curl
curl -I https://docs.example.com/old-page

接下来？