mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
f66b301e00
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
127 lines
5.2 KiB
Plaintext
127 lines
5.2 KiB
Plaintext
---
|
||
title: "使用 Vercel 在子路径下部署"
|
||
sidebarTitle: "Vercel"
|
||
description: "通过 Vercel 重写规则将你的 Mintlify 站点托管在主域名的子路径下，并附有分步的 vercel.json 配置演练。"
|
||
keywords: ["vercel.json", "Vercel 部署", "重写规则配置", "子路径路由", "外部代理", "CloudFront", "域名验证", "SSL 证书"]
|
||
boost: 3
|
||
---
|
||
|
||
import { VercelJsonGenerator } from "/snippets/zh/vercel-json-generator.mdx";
|
||
import SubpathSetupSteps from "/snippets/zh/subpath-setup-steps.mdx";
|
||
|
||
配置你的 `vercel.json` 文件，将主域名的请求代理到文档所在的子路径。
|
||
|
||
|
||
<div id="verceljson-file">
|
||
## vercel.json 文件
|
||
</div>
|
||
|
||
`vercel.json` 文件用于配置项目的构建和部署方式。它位于项目的根目录，用来控制部署的各个方面，包括路由、重定向、请求头以及构建设置。
|
||
|
||
我们会在你的 `vercel.json` 文件中使用 `rewrites` 配置，将来自主域名的请求代理到你的文档站点。
|
||
|
||
Rewrites 会在不更改浏览器中 URL 的情况下，将传入请求映射到不同的目标。当有人访问 `yoursite.com/docs` 时，Vercel 会在内部从 `your-subdomain.mintlify.site/docs` 获取内容，但用户在浏览器中仍然看到的是 `yoursite.com/docs`。这与重定向不同，后者会将用户直接带到另一个完全不同的 URL。
|
||
|
||
<div id="configuration">
|
||
## 配置
|
||
</div>
|
||
|
||
<div id="host-at-docs-subpath">
|
||
### 在 `/docs` 子路径下托管
|
||
</div>
|
||
|
||
1. 在控制台中前往 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain)。
|
||
2. 启用 **Host at** 开关。
|
||
3. 输入你的域名。
|
||
4. 输入 `docs` 作为你的基础路径。
|
||
5. 选择 **Add domain**。
|
||
5. 在你的 `vercel.json` 文件中添加以下重写规则。将 `[subdomain]` 替换为你的子域，它出现在控制台 URL 的末尾。例如，`app.mintlify.com/your-organization/your-subdomain` 的子域标识符是 `your-subdomain`。
|
||
|
||
```json
|
||
{
|
||
"rewrites": [
|
||
{
|
||
"source": "/_mintlify/:path*",
|
||
"destination": "https://[subdomain].mintlify.site/_mintlify/:path*"
|
||
},
|
||
{
|
||
"source": "/api/request",
|
||
"destination": "https://[subdomain].mintlify.site/_mintlify/api/request"
|
||
},
|
||
{
|
||
"source": "/docs",
|
||
"destination": "https://[subdomain].mintlify.site/docs"
|
||
},
|
||
{
|
||
"source": "/docs/:match*",
|
||
"destination": "https://[subdomain].mintlify.site/docs/:match*"
|
||
},
|
||
{
|
||
"source": "/mintlify-assets/:path+",
|
||
"destination": "https://[subdomain].mintlify.site/mintlify-assets/:path+"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
`rewrites` 配置会将你域名上的 `/docs` 子路径映射到你的文档站点上的 `/docs` 子路径。
|
||
|
||
- **`source`**：你域名上触发重写的路径模式。
|
||
- **`destination`**：请求应被代理到的位置。
|
||
- **`:match*`**：用于捕获子路径之后任意路径片段的通配符。
|
||
|
||
`/_mintlify` 和 `/mintlify-assets` 重写规则是 API playground 和静态资源正常工作所必需的。
|
||
|
||
如需了解更多信息，请参阅 Vercel 文档中的 [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)。
|
||
|
||
<div id="host-at-custom-subpath">
|
||
### 在自定义子路径下托管
|
||
</div>
|
||
|
||
要使用自定义子路径（任何非 `/docs` 的路径）：
|
||
|
||
<SubpathSetupSteps />
|
||
|
||
然后使用下面的生成器创建你的重写规则配置，并将这些重写规则添加到你的 `vercel.json` 文件中。
|
||
|
||
Mintlify 会重新构建你的文档以在你的基础路径下提供服务，因此你的文档文件不需要位于与子路径相匹配的目录中。
|
||
|
||
<VercelJsonGenerator />
|
||
|
||
<div id="external-proxies-in-front-of-vercel">
|
||
## Vercel 前的外部代理
|
||
</div>
|
||
|
||
如果你在 Vercel 部署前使用了 Cloudflare 或 AWS CloudFront 等外部代理，请对其进行正确配置。这样可以避免与 Vercel 的域名验证和 SSL 证书签发流程发生冲突。
|
||
|
||
错误的代理配置可能会阻止 Vercel 签发 Let's Encrypt SSL 证书，并导致域名验证失败。
|
||
|
||
请参阅 Vercel 文档中的[支持的提供商](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite)。
|
||
|
||
<div id="required-path-allowlist">
|
||
### 必需的路径白名单
|
||
</div>
|
||
|
||
你的外部代理必须允许访问以下特定路径的流量，不得阻止、重定向或进行强缓存：
|
||
|
||
- `/.well-known/acme-challenge/*`：用于 Let's Encrypt 证书验证。
|
||
- `/.well-known/vercel/*`：用于 Vercel 域名验证。
|
||
- `/mintlify-assets/_next/static/*`：用于静态资源。
|
||
|
||
这些路径应直接透传到你的 Vercel 部署，不进行任何修改。
|
||
|
||
<div id="header-forwarding-requirements">
|
||
### 请求头转发要求
|
||
</div>
|
||
|
||
确保你的代理正确转发 `Host` 请求头。如果请求头未正确转发，验证请求会失败。
|
||
|
||
<div id="test-your-proxy-setup">
|
||
### 测试你的代理配置
|
||
</div>
|
||
|
||
要验证你的代理是否已正确配置：
|
||
|
||
1. 测试 `https://[yourdomain].com/.well-known/vercel/` 是否有响应。
|
||
2. 确认 SSL 证书已在你的 Vercel 控制台中正确签发并生效。
|
||
3. 检查 domain 验证是否已成功完成。 |