Skip to main content
配置你的 vercel.json 文件,将主域名的请求代理到文档所在的子路径。

vercel.json 文件

vercel.json 文件用于配置项目的构建和部署方式。它位于项目的根目录,用来控制部署的各个方面,包括路由、重定向、请求头以及构建设置。 我们会在你的 vercel.json 文件中使用 rewrites 配置,将来自主域名的请求代理到你的文档站点。 Rewrites 会在不更改浏览器中 URL 的情况下,将传入请求映射到不同的目标。当有人访问 yoursite.com/docs 时,Vercel 会在内部从 your-subdomain.mintlify.site/docs 获取内容,但用户在浏览器中仍然看到的是 yoursite.com/docs。这与重定向不同,后者会将用户直接带到另一个完全不同的 URL。

配置

/docs 子路径下托管

  1. 在控制台中前往 Custom domain setup
  2. 启用 Host at 开关。
  3. 输入你的域名。
  4. 输入 docs 作为你的基础路径。
  5. 选择 Add domain
  6. 在你的 vercel.json 文件中添加以下重写规则。将 [subdomain] 替换为你的子域,它出现在控制台 URL 的末尾。例如,app.mintlify.com/your-organization/your-subdomain 的子域标识符是 your-subdomain
rewrites 配置会将你域名上的 /docs 子路径映射到你的文档站点上的 /docs 子路径。
  • source:你域名上触发重写的路径模式。
  • destination:请求应被代理到的位置。
  • :match*:用于捕获子路径之后任意路径片段的通配符。
/_mintlify/mintlify-assets 重写规则是 API playground 和静态资源正常工作所必需的。 如需了解更多信息,请参阅 Vercel 文档中的 Configuring projects with vercel.json: Rewrites

在自定义子路径下托管

要使用自定义子路径(任何非 /docs 的路径):
  1. 在控制台中前往 Custom domain setup 页面。
  2. 启用 Host at 开关并输入你的基础路径。例如 /docs/help
  3. 输入你的域名。
  4. 输入你的基础路径。
  5. 选择 Add domain
然后使用下面的生成器创建你的重写规则配置,并将这些重写规则添加到你的 vercel.json 文件中。 Mintlify 会重新构建你的文档以在你的基础路径下提供服务,因此你的文档文件不需要位于与子路径相匹配的目录中。

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. 确认 SSL 证书已在你的 Vercel 控制台中正确签发并生效。
  3. 检查 domain 验证是否已成功完成。