​
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. 检查域名验证是否已成功完成。