跳转到主要内容

​
vercel.json 文件

vercel.json 文件用于配置项目的构建与部署方式。它位于项目根目录，控制部署的各个方面，包括路由、重定向、响应头和构建设置。 我们使用 rewrites 配置，将来自主 domain 的请求代理到你的文档站点。 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: 会在你的 domain 上触发重写的路径模式。
  • destination: 请求应被代理到的目标地址。
  • :match*: 一个通配符，用于捕获子路径之后的任意路径片段。
更多信息请参阅 Vercel 文档：使用 vercel.json 配置项目：Rewrites。

​
生成重写规则

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

​
在 Vercel 中使用外部代理

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

​
必需的路径允许列表

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

​
请求头转发要求

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

​
测试你的代理设置

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