# 使用 Vercel 在子路径下部署 (/zh/deploy/vercel)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 844 · updated: 2026-09-23 -->
Related: [Monorepo 设置](/zh/deploy/monorepo.md), [多仓库部署](/zh/deploy/multi-repo.md), [部署](/zh/deploy/deployments.md), [预览部署](/zh/deploy/preview-deployments.md), [GitHub](/zh/deploy/github.md), [GitHub Enterprise Server](/zh/deploy/ghes.md)

配置你的 `vercel.json` 文件，将主域名的请求代理到文档所在的子路径。

<div id="verceljson-file">
  ## vercel.json 文件 [#verceljson-文件]
</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` 子路径下托管 [#在-docs-子路径下托管]
</div>

1. 在控制台中前往 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain)。
2. 启用 **Host at** 开关。
3. 输入你的域名。
4. 输入 `docs` 作为你的基础路径。
5. 选择 **Add domain**。
6. 在你的 `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` 的路径）：

1. 在控制台中前往 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) 页面。
2. 启用 **Host at** 开关并输入你的基础路径。例如 `/docs` 或 `/help`。
3. 输入你的域名。
4. 输入你的基础路径。
5. 选择 **Add domain**。

然后使用下面的生成器创建你的重写规则配置，并将这些重写规则添加到你的 `vercel.json` 文件中。

Mintlify 会重新构建你的文档以在你的基础路径下提供服务，因此你的文档文件不需要位于与子路径相匹配的目录中。

<div id="external-proxies-in-front-of-vercel">
  ## 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 验证是否已成功完成。