Vercel 项目级路由规则模板零代码为/api配置外部源 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在 CDN 层为/api路径配置一条指向外部后端的 rewrite 路由规则让 API 流量直接经由自己的域名对外提供服务——无需改动代码、无需重新部署规则发布后即刻生效。这是本仓库 cdn/add-api-rewrite-routing-rule 模板的核心能力。读完本文你将掌握项目级路由规则的适用场景与运作原理、通过 Dashboard / CLI / API / SDK 四种方式创建并发布规则的具体操作以及如何叠加边缘缓存CDN-Cache-Control与定向缓存清除Vercel-Cache-Tag把一次普通代理升级为高性能的 CDN 网关文中还会结合仓库内同主题的代码化模板 cdn/api-proxy-rewrite 给出可对照的源码级实现。模板概览这条规则到底做了什么该模板生成的是一条项目级project-level路由规则其核心行为是匹配所有形如/api/:path*的请求通过 rewrite重写动作把请求转发到一个外部源站external origin外部源站的响应原样返回给客户端客户端看到的始终是当前域名源站地址不会暴露。原文档明确给出了这条规则在模板中的默认形态见 README.md 的 frontmatter 与使用说明字段默认值说明规则名称API Proxy用于在 Dashboard 中标识该规则匹配路径/api/:path*使用 path-to-regexp 模式:path*匹配任意数量路径段动作rewrite服务端转发客户端 URL 不变区别于 redirect目标地址https://api.example.com/$1$1引用:path*捕获的路径部分典型场景API 独立托管在别的平台/机房但你希望它通过 Vercel 域名对外服务从而规避跨域CORS问题、对客户端隐藏真实后端地址同时让 Vercel CDN 站在后端前面借助全球边缘网络提升性能并通过内置缓存降低成本再叠加 Vercel Firewall 提供安全防护层。项目级路由规则为什么能做到不改代码就改路由项目级路由规则是 Vercel 在CDN 层提供的路由管理能力它与写在代码里的vercel.json/vercel.ts路由配置是两套并存机制代码内路由随部署生效需要重新部署才能变更项目级路由规则在项目上独立维护发布后即刻生效不触发部署、不动代码。因此它非常适合运维期微调临时把某个 API 路径切到新后端、灰度期间调整目标地址、紧急把流量导向备用源站都可以在几十秒内完成且可通过 Dashboard、CLI、REST API 或 SDK 任意一种方式配置原文档 Overview 一节即说明这一点。使用步骤Dashboard 可视化创建按照原文档的 To use 章节无代码方式的操作流程如下在模板页面点击Add Route该按钮携带预填参数打开的是新建路由表单路径/cdn/routing/new参数已含规则名API Proxy、路径/api/:path*、语法pattern、动作rewrite以及目标https://api.example.com/$1选择你的team与project把目标地址https://api.example.com/$1替换为你的真实后端地址保留$1占位符它会被:path*捕获的实际路径替换保存规则review 变更内容点击Publish激活。发布后无需任何部署/api/**的请求即开始被代理到新地址。定制项详解让规则贴合你的 API 形态原文档 Consider customization 一节给出四条建议这里逐条展开Destination目标地址核心必改项。把示例地址换成真实后端注意保留$1捕获组否则:path*匹配到的路径段会丢失转发后路径残缺。Path pattern路径模式默认/api/:path*覆盖全部 API 子路径。若只需代理特定前缀可改为如/api/v1/:path*、/api/posts/:path*避免无关请求被转发到后端增加无谓流量。Response headers响应头添加CDN-Cache-Control响应头让 CDN 边缘缓存该路径的响应。它与浏览器缓存头Cache-Control的区别在于CDN-Cache-Control只作用于 CDN 层在响应到达浏览器之前会被剥离因此可以放心设置较激进的缓存策略而不影响用户侧缓存语义此语义在 cdn/api-proxy-rewrite/README.md 的 CDN caching 一节有明确说明。Cache tags缓存标签添加Vercel-Cache-Tag响应头为缓存内容打标签从而在需要时只清除打了该标签的缓存而不必清空整个项目的 CDN 缓存。通过 Vercel CLI 配置原文档提供了完整的 CLI 操作序列README.md 的 Vercel CLI 一节创建规则并发布vercel routes add API Proxy \ --src /api/:path* \ --src-syntax path-to-regexp \ --action rewrite \ --dest https://api.example.com/:path* \ --yes vercel routes publish --yes各参数含义与取值范围如下参数取值示例说明vercel routes add 名称API Proxy规则名称Dashboard 中以此显示--src/api/:path*匹配的请求路径模式--src-syntaxpath-to-regexp路径匹配语法本模板使用 path-to-regexp--actionrewrite动作类型rewrite 为服务端代理转发--desthttps://api.example.com/:path*目标地址:path*透传捕获的路径段--yes—跳过交互确认直接创建vercel routes publish --yes—将已添加的规则发布生效对应 Dashboard 的 Publish 按钮注意CLI 的目标地址中:path*与 Dashboard 预填地址中的$1是同一语义的两种写法都表示把:path*捕获的路径原样带到目标地址。通过 REST API 与 SDK 配置原文档说明路由规则同样可以使用Vercel REST API项目路由的 add a routing rule 端点或Vercel SDK配置。这两种方式适合需要把路由规则纳入自动化流水线CI/CD、脚本批量管理的团队——例如根据环境动态切换目标后端、跨多项目批量下发同构规则均可通过 API/SDK 编程化完成与 CLI 和 Dashboard 写入的是同一份项目级规则配置。代码化方案对照vercel.ts中的等价实现如果希望把代理外部 API这一配置纳入版本控制、随代码一起演进仓库提供了完全对等的代码化模板 cdn/api-proxy-rewrite原文档 Code-based approach 一节所指核心配置集中在 vercel.tsimport { routes, type VercelConfig } from vercel/config/v1 const EXTERNAL_API_URL process.env.EXTERNAL_API_URL || https://jsonplaceholder.typicode.com export const config: VercelConfig { framework: nextjs, outputDirectory: .next, rewrites: [ routes.rewrite( /api/external/:path*, ${EXTERNAL_API_URL}/:path*, ), ], headers: [ routes.header(/api/external/:path*, [ { key: CDN-Cache-Control, value: public, max-age60, stale-while-revalidate3600, }, { key: Vercel-Cache-Tag, value: api, }, ]), ], }逐段对照解读外部地址可配置EXTERNAL_API_URL支持用环境变量覆盖未设置时回退到演示用的jsonplaceholder.typicode.com。该变量在构建期被读取因此修改后需要重新部署才生效这一点在 app/blog/page.tsx 的页面说明中也有明确标注。rewrite 规则routes.rewrite(/api/external/:path*, ${EXTERNAL_API_URL}/:path*)与项目级规则的/api/:path*→https://api.example.com/$1是同一逻辑只是路径前缀改为/api/external:path*捕获的路径段被透传到目标地址。边缘缓存头为同一路径追加CDN-Cache-Control: public, max-age60, stale-while-revalidate3600。缓存标签头追加Vercel-Cache-Tag: api为缓存内容打上api标签。前端消费链路请求如何走通该模板的 app/blog/page.tsx 展示了完整调用链博客页组件在useEffect中执行fetch(/api/external/posts)L118-L132→ 请求到达 Vercel → 命中 rewrite 规则被代理到外部 API → 响应携带缓存头回传并缓存。若请求失败例如本地开发、环境变量未配置页面会降级展示配置引导Onboarding界面。整个流程可归纳为原文档 README 中列出的四步页面请求/api/external/posts→ rewrite 匹配并代理 →CDN-Cache-Control控制边缘缓存 →Vercel-Cache-Tag支持定向清除。缓存语义详解max-age与stale-while-revalidate以 cdn/api-proxy-rewrite 的说明为准max-age60CDN 在 60 秒内直接命中缓存返回不触达外部 API从而显著降低源站压力与回源成本stale-while-revalidate360060 秒窗口过后CDN立即返回陈旧内容保证首字节速度同时在后台异步拉取最新副本更新缓存实现永远不慢、最终一致。这套组合非常适合允许短暂滞后的列表类接口如博客文章、商品目录配合CDN-Cache-Control只影响 CDN 不影响浏览器的特性可以安全地全局生效。定向缓存清除按标签 Purge打上Vercel-Cache-Tag: api标签后可以只清除带该标签的缓存而无需清空整个项目缓存。仓库 README 给出了两种操作方式Dashboard进入CDN Caches选择Cache Tag输入api点击PurgeCLIvercel cache invalidate --tag api这在后端数据刚发生变更、希望立即刷新代理缓存的场景下特别有用——例如发布新文章后一条命令即可让/api/external/posts的下一次请求回源拿到新数据同时不影响其他路径的缓存命中率。本地开发与部署注意事项需要特别提醒的边界来自 app/blog/page.tsx 底部说明vercel.ts中定义的 rewrite 只在 Vercel 平台生效。本地pnpm dev开发时不会执行代理页面会始终显示配置引导页而非真实数据本地环境变量修改后也要注意该值在构建期被读取的特性。若要在本地验证代理效果需借助vercel dev或部署到 Vercel 后测试。总结两条路线如何选择至此围绕把/api流量代理到外部源站这一目标仓库给出了两条可落地的路线二者可互补使用对比维度项目级路由规则本文主题模板代码化vercel.tsapi-proxy-rewrite配置位置Dashboard / CLI / API / SDK仓库代码 vercel.ts生效方式Publish 后即刻生效无需部署随代码重新部署版本控制规则存于项目配置非代码库随仓库走 Git 版本管理适用场景运维期快速调整、临时切源希望配置可审计、可复现、随环境变量变化对于API 独立托管、想通过 Vercel 域名统一入口并享受 CDN 加速与定向缓存清除的诉求项目级路由规则提供了一条零代码、零部署的捷径而需要把路由与缓存配置纳入代码资产时cdn/api-proxy-rewrite 的vercel.ts实现则给出了开箱即用的完整参考。【免费下载链接】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），仅供参考