mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
cf671d7abf
* docs: address gaps in recently updated pages * docs: translate page-gap fixes to es, fr, zh * Apply suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> * Update multi-repo.mdx * add line breaks --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
138 lines
4.1 KiB
Plaintext
138 lines
4.1 KiB
Plaintext
---
|
||
title: "重定向"
|
||
description: "在 docs.json 中配置 URL 重定向规则，为已移动、重命名或删除的文档页面保留 SEO 排名，并防止读者遇到失效链接。"
|
||
keywords: ["redirects"]
|
||
boost: 3
|
||
---
|
||
|
||
当你更改 docs 文件夹中文件的路径时，该页面的 URL 路径也会随之改变。这通常发生在重构文档或更改侧边栏标题时。
|
||
|
||
<div id="redirects">
|
||
## 重定向
|
||
</div>
|
||
|
||
<Note>
|
||
重定向的**来源路径**不能包含像 `path#anchor` 这样的 URL 锚点，或像 `path?query=value` 这样的查询参数。目标路径可以包含锚点（例如 `/destination/path#section`）。
|
||
</Note>
|
||
|
||
在 `docs.json` 文件的顶层添加 `redirects` 字段即可设置重定向。
|
||
|
||
```json docs.json
|
||
{
|
||
"name": "My docs",
|
||
"redirects": [
|
||
{
|
||
"source": "/source/path",
|
||
"destination": "/destination/path"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
该重定向会将 `/source/path` 重定向到 `/destination/path`。
|
||
|
||
默认情况下，重定向为永久重定向 (308)。若要使用临时重定向 (307)，请将 `permanent` 设置为 `false`。
|
||
|
||
```json
|
||
"redirects": [
|
||
{
|
||
"source": "/source/path",
|
||
"destination": "/destination/path",
|
||
"permanent": false
|
||
}
|
||
]
|
||
```
|
||
|
||
307 和 308 都保留原始请求的 HTTP 方法 (不同于 301 和 302) ，因此适合用于重定向 POST 请求。
|
||
|
||
当页面已彻底迁移时使用永久重定向 (308) — 适用于重命名的 slug、重构后的导航，或映射到替代页面的已删除页面。搜索引擎会将 SEO 排名转移到目标地址，浏览器也会缓存此重定向。
|
||
|
||
当源 URL 未来还会重新启用时，使用临时重定向 (307) 进行短期转向，例如维护页面、A/B 测试或你计划复用的营销链接。搜索引擎会在索引中保留源 URL，且不会转移排名。
|
||
|
||
<div id="redirect-limits">
|
||
### 重定向数量限制
|
||
</div>
|
||
|
||
对可以在 `docs.json` 中定义的重定向数量没有硬性上限。非常大的重定向数组 (数千条) 可能会拖慢部署速度并让文件难以审查，因此请尽可能使用[通配符重定向](#wildcard-redirects)进行合并。
|
||
|
||
<div id="wildcard-redirects">
|
||
### 通配符重定向
|
||
</div>
|
||
|
||
要匹配通配符路径，请在参数后面使用 `*`。在此示例中，`/beta/:slug*` 可匹配 `/beta/introduction`，并将其重定向到 `/v2/introduction`。
|
||
|
||
```json
|
||
"redirects": [
|
||
{
|
||
"source": "/beta/:slug*",
|
||
"destination": "/v2/:slug*"
|
||
}
|
||
]
|
||
```
|
||
|
||
<div id="partial-wildcard-redirects">
|
||
### 部分通配符重定向
|
||
</div>
|
||
|
||
使用部分通配符来匹配以特定前缀开头的 URL 片段。
|
||
|
||
```json
|
||
"redirects": [
|
||
{
|
||
"source": "/articles/concepts-*",
|
||
"destination": "/collections/overview"
|
||
}
|
||
]
|
||
```
|
||
|
||
这会匹配任何路径为 `/articles/concepts-` 的 URL，例如 `/articles/concepts-getting-started` 和 `/articles/concepts-overview`，并将它们全部重定向到 `/collections/overview`。
|
||
|
||
你也可以在目标地址中使用捕获到的通配符值进行替换。
|
||
|
||
```json
|
||
"redirects": [
|
||
{
|
||
"source": "/old/article-*",
|
||
"destination": "/new/article-*"
|
||
}
|
||
]
|
||
```
|
||
|
||
该重定向会将 `/old/article-123` 重定向到 `/new/article-123`，并在前缀之后保留捕获到的值。
|
||
|
||
<div id="avoid-infinite-redirects">
|
||
### 避免无限重定向
|
||
</div>
|
||
|
||
为避免出现无限循环，请不要创建路径彼此重定向的循环规则。
|
||
|
||
```json
|
||
"redirects": [
|
||
{
|
||
"source": "/docs/:slug*",
|
||
"destination": "/help/:slug*"
|
||
},
|
||
{
|
||
"source": "/help/:slug*",
|
||
"destination": "/docs/:slug*"
|
||
}
|
||
]
|
||
```
|
||
|
||
<div id="when-redirects-take-effect">
|
||
## 重定向何时生效
|
||
</div>
|
||
|
||
`docs.json` 中的重定向会在请求时由 Mintlify 的托管层应用，因此一旦你的改动部署完成，它们就会立即生效。预览部署同样会应用重定向，便于你在合并到生产分支之前验证其行为。
|
||
|
||
要在本地测试重定向，请运行 `mint dev`，并在浏览器中访问源路径。本地开发服务器会应用你在 `docs.json` 中定义的重定向。
|
||
|
||
<div id="check-for-broken-links">
|
||
## 检查无效链接
|
||
</div>
|
||
|
||
使用 [CLI](/zh/cli) 检测无效链接。
|
||
|
||
```bash
|
||
mint broken-links
|
||
``` |