跳转到主要内容

​
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。

​
配置

​
从 /docs 提供托管

  1. 在你的控制台前往 自定义 domain 设置。
  2. 将 在 /docs 托管 开关切换为开启。
自定义 domain 设置页面的截图。“在 `/docs` 托管”开关已开启，并用橙色矩形标出。
  1. 输入你的 domain。
  2. 选择 添加 domain。
  3. 将以下重写规则添加到你的 vercel.json 文件中。将 [subdomain] 替换为你的子域：
  {
    "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。

​
从自定义路径托管

要使用自定义子路径（/docs 之外的任意路径），必须在存储库中按该子路径的结构组织文档文件。举例来说，如果文档托管在 yoursite.com/help，则文档文件必须位于 help/ 目录下。 使用下面的生成器创建重写配置，并将这些重写添加到 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