跳转到主要内容

​
vercel.json 文件

vercel.json 文件用于配置项目的构建和部署。它位于项目根目录，控制部署的各个方面，包括路由、重定向、请求头和构建设置。 我们使用 rewrites 配置将主域名的请求代理到你的文档站点。 Rewrites 会将传入请求映射到其他目标，但不会更改浏览器地址栏中的 URL。当有人访问 yoursite.com/docs 时，Vercel 会在内部从 your-subdomain.mintlify.dev/docs 拉取内容，但用户在浏览器中仍然看到 yoursite.com/docs。这与重定向不同，重定向会将用户带到一个完全不同的 URL。 你可以将子路径自定义为任意值，例如 /docs、/help 或 /guides。此外，也可以使用更深层级的嵌套子路径，如 /product/docs。

​
仓库结构

你的文档文件需要在仓库中按照你选择的子路径结构进行组织。比如，如果你希望文档位于 yoursite.com/docs，应创建一个 docs/ 目录，并将所有文档文件置于其中。

​
配置

要在 Vercel 上将文档托管到自定义子路径下，请在 vercel.json 文件中添加以下配置。示例使用的是 /docs，你也可以替换为任意子路径： 
{
  "rewrites": [
    {
      "source": "/docs",
      "destination": "https://[subdomain].mintlify.dev/docs"
    },
    {
      "source": "/docs/:match*",
      "destination": "https://[subdomain].mintlify.dev/docs/:match*"
    }
  ]
}
  • source: 触发重写的域内路径匹配模式。
  • destination: 请求应被代理到的目标地址。
  • :match*: 通配符，用于捕获子路径之后的任意路径片段。
更多信息请参阅 Vercel 文档：使用 vercel.json 配置项目：Rewrites（重写）。

​
生成重写规则

输入你的子域名和自定义子目录，为你的 vercel.json 文件生成相应的重写规则。

​
在 Vercel 中使用外部代理

如果你在 Vercel 部署前方使用外部代理（如 Cloudflare 或 AWS CloudFront），必须正确配置，避免与 Vercel 的域名验证和 SSL 证书签发产生冲突。 错误的代理配置可能会阻止 Vercel 为你签发 Let’s Encrypt SSL 证书，并导致域名验证失败。 请参阅 Vercel 文档中的受支持的服务商。

​
必需的路径白名单

你的外部代理必须允许以下特定路径的流量通过，不得拦截、重定向或进行强制缓存：
  • /.well-known/acme-challenge/* - 用于 Let’s Encrypt 证书验证
  • /.well-known/vercel/* - 用于 Vercel 域名验证
  • /mintlify-assets/_next/static/* - 用于静态资源
这些路径应直接无修改地透传到你的 Vercel 部署。

​
头部转发要求

确保你的代理正确转发 HOST 头部。若未正确转发该头部，验证请求将失败。

​
测试代理设置

要验证代理是否已正确配置：
  1. 测试 https://[yourdomain].com/.well-known/vercel/ 是否能返回响应。
  2. 在 Vercel 控制台确认 SSL 证书已正确签发。
  3. 检查域名验证是否已成功完成。