Vercel Build Output API 之 Prerender Functions 实战：构建期预渲染、回退页面与按需失效

Vercel Build Output API 之 Prerender Functions 实战构建期预渲染、回退页面与按需失效【免费下载链接】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/examplesPrerender Functions 是 Vercel Build Output API构建产物 API提供的一种特殊 Serverless 函数它在构建期即可为热门路径预先渲染出页面并缓存请求命中缓存时由边缘网络直接返回未命中时再由函数动态生成。本文以本仓库中的 prerender-functions 示例 为核心完整拆解其部署产物结构、路由配置、fallback 回退机制与按需重新验证On-Demand ISR方案读完你就能照此结构手工构建一个支持“构建期预渲染 运行期按需生成 缓存失效”的博客站点。背景什么是 Prerender Functions在 Vercel 的 Build Output API 体系中一次部署的最终产物被统一组织在.vercel/output目录下Vercel 会根据该目录的布局自动识别出静态文件、Serverless 函数、路由规则等不同原语Primitives。本仓库的 build-output-api 总览 就是一组“预构建prebuilt”项目示例每个子目录对应一种原语Prerender Functions 正是其中之一。Prerender Function 可以理解为一种“带缓存配置的 Serverless 函数”它本质上仍然是一个.func目录中的函数但旁边多了一份name.prerender-config.json配置文件。这份配置告诉 Vercel 该函数应该被当作 Prerender 原语处理——也就是说构建期你可以预先为一批路径渲染好内容让它们直接命中缓存运行期未被预渲染的路径首次被访问时函数会动态生成内容并写入缓存之后同一路径的请求将直接由缓存/边缘网络响应函数不再被调用。它与纯 Serverless Functions 示例每次请求都执行函数和纯 Static Files 示例完全静态、无函数参与之间的差别正是“动态内容 缓存”的组合方式。示例总览一个由虚构 CMS 驱动的博客本示例的场景非常直观Prerender Function 从一个虚构的 CMS“后端服务”渲染博客文章。为了演示“构建期预渲染”的效果示例中有一批“热门popular”博客文章会在构建时被预先渲染出来并放入static目录。整体请求处理链路可以概括为三步构建期热门文章的页面被预渲染为静态产物随部署一起发布运行期路由所有以/blog/*开头的 HTTP 请求被config.json中的路由规则指向 Prerender Function缓存与回退请求对应路径若已渲染则直接返回缓存内容若尚未渲染则使用可选的 fallback回退文件作为占位响应随后由函数完成真实渲染并写入缓存。部署产物结构详解按照 README 的描述该示例的核心部署产物位于.vercel/output下关键组件有三个1. 函数本体functions/blog/page.func这是一个标准的 Serverless Function 目录位于.vercel/output/functions/blog/page.func。它负责渲染博客文章页面。函数内部通常会包含入口脚本、运行时依赖如node_modules以及对应的.vc-config.json声明 runtime、handler 等其组织方式与 serverless-functions 示例 中讲解的index.func完全一致。2. 预渲染配置functions/blog/page.prerender-config.json与.func目录同级的这份 JSON 配置文件是“Prerender”身份的关键位于.vercel/output/functions/blog/page.prerender-config.json。按照 Build Output API v3 规范这类配置文件通常包含以下核心字段{ expiration: 3600, bypassToken: randomly-generated-bypass-token, allowQuery: [utm_source, utm_medium], fallback: blog-fallback.html }各字段的典型含义如下字段作用expiration缓存过期时间秒。在此时间内同一路径的请求直接命中缓存设为0表示不缓存、每次回源执行函数bypassToken绕过缓存的令牌用于触发按需重新验证详见下文“按需失效”一节allowQuery允许参与缓存的查询参数白名单用于精细化控制缓存键fallback指定 fallback 回退文件的路径用于处理尚未渲染的路径说明上述字段为 Build Output API v3 对 prerender 配置的通用约定本仓库的 README 明确指出该示例包含page.prerender-config.json但示例的.vercel/output构建产物本身并未提交到仓库中字段值请以你实际构建生成的配置文件为准。3. 回退文件fallbackREADME 特别强调示例还包含一个可选的 fallback 文件。它的作用是当某个博客文章路径“尚未被渲染”时Vercel 会先把这个回退页面返回给用户而不是 404 或空白同时函数在后台完成该页面的渲染并缓存。这样既保证了首访体验又实现了“需要时才生成”的按需渲染。4. 路由规则config.json在.vercel/output/config.json中有一条路由负责把所有/blog/*前缀下的 HTTP 请求导向 Prerender Function。这正是 Routes 示例 所讲解的路由机制的应用通过routes属性把 URL 路径与具体的函数或静态文件绑定。类似地你也可以通过路由实现重定向、改写等更复杂的场景。预渲染 回退的组合流程把上述组件串起来一次请求的完整生命周期如下用户访问/blog/some-post请求命中config.json中的/blog/*路由被导向page.funcVercel 检查该路径是否已有渲染结果命中缓存如构建期预渲染的热门文章或之前已动态生成过的路径直接返回缓存的 HTML函数不执行未命中返回 fallback 文件作为首屏响应同时调用 Prerender Function 渲染真实页面并写入缓存后续访问直接命中。这也是“热门文章构建期预渲染、冷门文章首次访问时按需生成”这一博客场景在边缘网络上的标准实现方式。部署与验证本仓库中的 Build Output API 示例均为“预构建prebuilt”项目部署方式统一为在示例目录内执行见 build-output-api 总览cd build-output-api/prerender-functions vercel deploy --prebuilt关键点在于--prebuilt标志它告知 Vercel 直接使用项目现有的.vercel/output构建产物进行部署而不再执行框架的构建流程。因此只要你的.vercel/output目录布局符合规范函数、prerender 配置、路由、静态文件齐全即可一键上线。按需失效On-Demand ISR 与 bypassToken构建期预渲染解决了“冷启动”问题但内容更新后如何让缓存失效仓库中的 on-demand-isr 示例 给出了 Prerender Functions 的标准答案——按需重新验证On-Demand ISR对一个 Prerender Function 对应的路径发起GET或HEAD请求并携带请求头x-prerender-revalidate: bypassToken其中的bypassToken必须与该函数对应的name.prerender-config.json中的bypassToken值一致校验通过后缓存会被立即重新验证绕过 Vercel 常规的缓存行为强制回源渲染最新内容。这意味着你可以把“文章更新/发布”这类事件与重新验证请求关联起来CMS 数据变更时由后端或定时任务向对应路径发起携带正确bypassToken的重新验证请求即可精确地只刷新受影响的页面而无需重新部署整个站点。安全最佳实践Prerender 配置中的令牌直接决定了“谁能触发缓存失效”因此必须谨慎对待bypassToken必须随机化示例代码为了方便演示使用了固定值但生产环境应当在构建时生成随机字符串且绝不能暴露给用户或客户端除非处于已认证的场景下见 on-demand-isr 的安全说明保护一切能触发重新验证的入口若你的方案中还使用了authToken或自定义的重新验证处理器必须按生产级标准做好鉴权防止恶意请求刷掉缓存或制造不必要的回源压力。与同目录其它示例的关系Prerender Functions 并不是孤立概念它与 Build Output API 的其它原语紧密配合仓库中对应的姊妹示例可以对照阅读Serverless FunctionsPrerender Function 的函数本体就是标准 Serverless Function理解.func目录与.vc-config.json是基础Static Files构建期预渲染的产物本质上是静态文件二者共用静态产物发布机制Routes/blog/*的路由规则正是 Routes 机制的实战应用On-Demand ISR讲解 Prerender Function 缓存失效的完整实现含 HTML 与 API 两种响应类型的演示。小结本示例用最少的组件演示了 Build Output API 下 Prerender Functions 的完整工作流page.func提供渲染能力page.prerender-config.json声明缓存与回退策略config.json路由将/blog/*请求导向函数构建期预渲染保证热门内容秒开fallback 文件兜底未生成路径再配合x-prerender-revalidatebypassToken实现按需失效。掌握了这套结构你就能脱离框架直接用构建产物构建出具备“预渲染 缓存 按需更新”能力的生产级应用。【免费下载链接】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），仅供参考