使用 vercel.ts Rewrites 将 Mintlify 文档无缝集成到主域mintlify-docs-rewrite 示例深度解析【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples本指南围绕开源仓库中的 mintlify-docs-rewrite 示例 展开讲解如何借助 Vercel 的vercel.ts项目级配置把托管在 Mintlify 上的文档通过 rewrite 规则映射到产品站点的/docs路径实现文档与产品同域的统一体验。读完本文你将掌握vercel.ts重写规则的写法、MINTLIFY_DOCS_URL环境变量的用法以及针对第三方文档站所需的 Content-Security-Policy 响应头配置可以直接复用到自己的 Next.js 产品站点中。示例概览为什么要把文档搬进主域大多数 SaaS 产品把文档放在docs.yourdomain.com子域或独立的第三方站点上用户访问时需要跨域跳转体验割裂。这个模板演示的正是另一种做法文档继续由 Mintlify 托管但通过 Vercel 的vercel.ts配置做重写代理让用户直接访问产品主域的/docs就能看到文档——对用户而言文档就像产品站的一部分。仓库用一个虚构的产品站点Flux实时事件基础设施来演示这一效果其 README frontmatter 中记录了在线演示地址demoUrl与一键部署地址deployUrl字段部署后访问/docs即可看到经由主域代理出来的 Mintlify 文档页面。从仓库目录结构看这个示例是一个完整的 Next.jsApp Router项目cdn/mintlify-docs-rewrite/ ├── app/ │ ├── about/page.tsx # Flux 品牌介绍页 │ ├── globals.css # 全局样式Tailwind v4 │ ├── layout.tsx # 根布局引入 Navbar 与 Geist 字体 │ ├── not-found.tsx # 404 页面 │ └── page.tsx # 首页含指向 /docs 的 CTA ├── components/Navbar.tsx # 顶部导航含 Docs 入口 ├── vercel.ts # 核心rewrites headers 配置 ├── package.json ├── postcss.config.mjs ├── tsconfig.json └── pnpm-lock.yaml产品站首页 app/page.tsx 中有一个醒目的 Read Documentation → 按钮直接指向/docscomponents/Navbar.tsx 的导航栏同样提供了 Docs 链接。这些入口本身没有任何特殊逻辑——因为/docs在用户看来就是本站路径这正是 rewrite 方案无缝的体现。两种上手方式README 提供了两种使用该模板的方式均可在本地复现。方式一一键部署使用 README frontmatter 中记录的deployUrl携带MINTLIFY_DOCS_URL环境变量注入参数的 Vercel 部署链接即可在 Vercel 控制台直接克隆并部署该项目适合先跑通效果再深入研究配置的场景。方式二Clone 后本地运行使用create-next-app以本示例为模板初始化项目pnpm create next-app --example https://github.com/vercel/examples/tree/main/cdn/mintlify-docs-rewrite接着安装依赖并启动开发服务器pnpm install pnpm dev从 package.json 可以看到该项目的脚本定义dev使用next dev --turbopack开启 Turbopack 加速另有build、start、lint三个标准脚本。依赖方面使用了next^16.0.7、react^19.2.1、Tailwind CSS v4以及关键的vercel/config^0.0.22提供vercel.ts的类型与构建支持包管理器锁定为pnpm10.24.0。环境变量MINTLIFY_DOCS_URLREADME 明确规定了唯一需要配置的环境变量MINTLIFY_DOCS_URL—— 你的 Mintlify 自定义域名 URL例如https://your-subdomain.mintlify.dev你可以在 Vercel 项目设置中配置它也可以写入本地.env.local文件。在 vercel.ts 中可以看到它的读取方式与兜底逻辑const MINTLIFY_DOCS_URL process.env.MINTLIFY_DOCS_URL || https://vercel-fcadfe60.mintlify.dev当环境变量未设置时会回退到示例默认的 Mintlify 子域vercel-fcadfe60.mintlify.dev保证克隆下来即可演示。实际接入自己的文档时务必在 Mintlify 控制台完成自定义域名绑定再将对应域名填入该变量。注意Mintlify 侧默认子域名格式是your-subdomain.mintlify.devREADME 中的示例即采用该约定。核心原理vercel.ts 重写配置逐行解析整个方案的精髓集中在项目根目录的 vercel.ts 文件中。与next.config.js不同vercel.ts是 Vercel 项目级配置直接在 Vercel 平台边缘网络层面生效不进入 Next.js 的构建产物因此可以代理任何外部 URL。完整配置如下import type { VercelConfig } from vercel/config/v1 const MINTLIFY_DOCS_URL process.env.MINTLIFY_DOCS_URL || https://vercel-fcadfe60.mintlify.dev export const config: VercelConfig { framework: nextjs, outputDirectory: .next, rewrites: [ { source: /docs, destination: ${MINTLIFY_DOCS_URL}/docs, }, { source: /docs/:match*, destination: ${MINTLIFY_DOCS_URL}/docs/:match*, }, ], headers: [ { source: /(.*), headers: [ { key: Content-Security-Policy, value: default-src self; script-src self unsafe-inline unsafe-eval cdn.jsdelivr.net; style-src self unsafe-inline d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src self d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src self data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net; connect-src self *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src self *.mintlify.dev;, }, ], }, ], }几个关键点的解读rewrites两条规则缺一不可第一条精确匹配/docs第二条用:match*通配符捕获/docs下的所有子路径如/docs/introduction、/docs/api/overview并把匹配到的路径段透传给 Mintlify 的对应路径/docs/:match*。Mintlify 文档自身的路由正是挂在/docs前缀下因此这种映射能保持文档内部 URL 结构不变。framework: nextjs与outputDirectory: .next声明项目框架与构建输出目录这是vercel.ts配置的基础字段。destination是服务端代理而非 301 跳转Vercel 在边缘对匹配请求透明转发浏览器地址栏始终保持yourdomain.com/docs用户无感知。值得对比的是仓库中另一个示例 cdn/api-proxy-rewrite/vercel.ts 展示了同族 API 的另一种写法——通过vercel/config/v1导出的routes.rewrite()/routes.header()辅助函数定义重写与缓存头。两者的底层机制一致mintlify-docs-rewrite 采用更直接的裸对象写法方便读者看清source/destination字段的原始形态。关键细节为第三方文档站配置 CSP 响应头因为/docs内容来自 Mintlify 的 CDN页面中会加载大量第三方资源浏览器默认的 CSP 策略会拦截它们。因此vercel.ts中额外配置了一条覆盖全站的Content-Security-Policy响应头vercel.ts L18-L28逐项放行 Mintlify 文档页所需的资源域script-src允许cdn.jsdelivr.netMintlify 的脚本分发以及unsafe-inline/unsafe-eval文档站脚本常见需求style-src/font-src放行fonts.googleapis.com与*.cloudfront.netMintlify 的样式表与字体托管域img-src允许data:、blob:、*.mintcdn.com、mintcdn.com及cdn.jsdelivr.net覆盖文档中的图片与图标资源connect-src放行*.mintlify.dev、*.mintlify.com、api.mintlifytrieve.com等保证文档页内的 API 请求、搜索等交互正常frame-src允许*.mintlify.dev为可能的嵌入内容预留空间。这一段的经验是当你用 rewrite 代理第三方托管内容时除了配置路由还必须同步放行对方的资源域否则页面会出现白屏或功能缺失。不同文档平台的资源域不同接入自己的 Mintlify 站点时可按实际控制台报错微调这些域名。请求流转与工作流程README 将整体工作流概括为四个步骤结合源码可以更完整地还原整条链路在 Mintlify 侧配置自定义域名如your-subdomain.mintlify.dev并把该地址填入MINTLIFY_DOCS_URL环境变量vercel.ts导出 rewrite 规则将/docs与/docs/:match*映射到 Mintlify URLvercel.ts L8-L17Vercel 在边缘层透明代理请求用户在浏览器访问yourdomain.com/docs/...Vercel 边缘节点将该请求转发到 Mintlify同时保持浏览器地址栏 URL 不变响应回程时还会附带上一步配置的 CSP 响应头用户获得文档即本站一部分的体验从产品首页的 Read Documentation → 按钮进入/docs全程没有跨域跳转导航栏、品牌视觉保持一致。从代码结构看产品站本身首页 app/page.tsx、关于页 app/about/page.tsx、404 页完全不需要感知文档的存在所有代理逻辑都收敛在vercel.ts一处替换文档平台时只需改配置而无需动业务代码。关键收益README 明确列出了这一方案的五项收益与上面的实现一一对应更好的 SEO文档位于主域而非独立子域链接权重与收录集中在同一域名下无 CORS 问题内容最终由你的域名对外提供浏览器侧不存在跨域限制品牌无缝统一产品和文档共享导航、主题与视觉用户不感知切换配置极简只需设置一个环境变量并部署无需改动产品代码Mintlify 承担基础设施托管、CDN 与内容更新继续由 Mintlify 负责你专注写作。注意事项与扩展建议基于源码结构与配置可以推断出以下实践要点供接入时参考域名绑定是前提MINTLIFY_DOCS_URL应指向你在 Mintlify 中完成绑定的自定义域名子域形式而不是裸的mintlify.app默认域名否则代理目标不稳定路径前缀约定本模板假设文档根路径为/docs。若你的产品站需要其他前缀如/documentation只需同步修改两条rewrites规则中的source与destinationCSP 按需调整示例中的 CSP 覆盖了 Mintlify 当前的资源域集合接入后若发现控制台有被拦截的资源可在headers段增量放行多环境差异化MINTLIFY_DOCS_URL可结合 Vercel 的 Preview / Production 环境分别配置实现不同环境指向不同文档版本。这个模板的价值在于把外部托管内容接入主域这一常见需求收敛为一个可复制的模式一段vercel.ts重写规则 一组配套响应头 一个环境变量即可让第三方文档与自建产品站融为一体。参考仓库中 cdn/api-proxy-rewrite、cdn/cms-bulk-redirects 等同目录示例还能看到vercel.ts在 API 代理、批量重定向等更多场景下的用法进一步理解这一配置文件的表达能力。【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考