AI 摘要：本文详细介绍了如何在 Vercel 平台上为 Astro 静态网站配置按需增量静态再生成 (On-Demand ISR)。文章首先解释了 ISR 和按需 ISR 的概念及其适用场景，然后通过一步步的代码示例，指导读者如何初始化项目、添加 Vercel 适配器并配置 ISR 参数、创建动态页面，以及最关键的部分——如何通过一个受保护的 API 端点来手动触发缓存失效和页面重建，从而实现对静态内容更新时间的精细控制。

1. 概念解析
• 什么是 ISR：解释增量静态再生成 (ISR) 的概念，即无需重新构建或部署整个网站即可更新静态内容（如博客文章或 GET API 端点）。
• 什么是按需 ISR：对比传统基于 TTL（生存时间）的 ISR，说明按需 ISR 允许在 TTL 到期前手动使缓存失效并触发重建，从而更精确地控制内容的新鲜度。
• 适用场景：列举按需 ISR 的典型用例，如不常更新但更新后需立即生效的内容，或渲染成本高（计算、时间、外部 API 费用）的频繁访问内容。

2. 项目配置
• 初始化 Astro 项目：使用命令行工具创建一个包含 Tailwind CSS 和 React 的 Astro 项目，并初始化 Git。
• 添加 Vercel 适配器：通过 astro add vercel 命令添加适配器，并在 astro.config.mjs 文件中配置 ISR 参数，包括设置 bypassToken（用于授权缓存失效的密钥）和 exclude（排除 API 路由不被缓存）。

3. 实现与验证
• 创建动态页面：在首页添加一个显示服务器渲染时间戳的组件，用于验证缓存效果。部署后，刷新页面时间戳不变，且响应头 x-vercel-cache 显示 HIT，证实页面来自缓存。
• 实现按需失效端点：创建一个受保护的 API 端点 (/api/invalidate)，该端点接收 POST 请求，内部向目标路由发送带有 x-prerender-revalidate 头（值为 bypassToken）的 HEAD 请求，以触发缓存失效和重建，并验证响应头确认操作成功。
• 测试：通过 curl 命令调用该 API 端点，成功使首页缓存失效，再次访问首页时看到新的时间戳，证明按需 ISR 生效。

Shawn's Blog

On-Demand ISR For Astro on Vercel | Shawn's Blog

Here's how to set on-demand incremental static regeneration for an Astro website when deploying to Vercel.

AI 摘要：本文由 Vercel 的 Lydia Hallie 撰写，介绍如何利用 Vercel 的 Build Output API 构建一个基于 React 的简易 Web 框架，支持静态渲染（Static Rendering）、增量静态再生（Incremental Static Regeneration, ISR）、服务端渲染（Server-Side Rendering, SSR）、边缘函数（Edge Functions）和自动图片优化等功能。文章不仅讲解框架涉及的文件结构和构建流程，还展示如何将每种渲染模式映射为 Vercel 可识别的输出，从而部署到无服务器（Serverless）和 Edge 环境。虽然该示例为教学版，但完整演示了现代框架实现高性能与可扩展架构的关键思路。

1. 框架目标与核心组件
• 通过 Vercel Build Output API 构建自定义 Web 框架
• 实现静态页面、增量渲染、服务端渲染、边缘渲染和图片优化等现代框架功能
• 所有页面位于 pages/ 目录，并根据配置选择不同渲染策略（static、ssr、prerender 或 edge）

2. 页面设计与优化策略
• Landing Page：通过图片优化与 Edge 缓存提升首页首字节时间（TTFB）
• Products Page：结合静态与动态渲染，利用 ISR 实现自动再生更新
• Popular Page：借助 Edge Functions 根据用户地理位置实现个性化推荐

3. 框架实现细节
• Static Rendering：
• 使用 ReactDOMServer.renderToString 将组件预渲染为 HTML
• 输出文件结构至 .vercel/output/static，生成可 Hydrate 的 JS 包
• Incremental Static Regeneration (ISR)：
• 创建 .func 文件夹与 prerender-config.json 配置缓存过期与再生逻辑
• 增设 fallback HTML 提供渐进体验
• Serverless Functions：
• 每个动态页生成一个 Lambda（serverless）函数，用于按需（re）生成页面
• 利用 .vc-config.json 定义运行时、入口点与上下文
• Edge Server Rendering：
• 在 Edge Runtime 中使用 React 进行服务端渲染
• 动态注入 req 对象以生成个性化内容

4. 自动图片优化（Automatic Image Optimization）
• 自定义 Image 组件，将图片请求代理至 /_vercel/image
• 基于 vercel.config.js 生成 .vercel/output/config.json，统一图片格式（webp/avif）、域名和缓存策略

5. 构建与输出过程（Build Output）
• 遍历所有页面并执行对应的渲染方法
• 拷贝静态资源至 .vercel/output/static
• 自动创建 .vercel/output/config.json 配置文件
• 构建完成后可直接通过 Vercel 部署，享受边缘分发与函数服务

6. 结论
• 框架可作为理解现代渲染机制与 Vercel 部署架构的参考
• 虽非生产版本，但展示了现代框架（如 Next.js）背后的核心逻辑
• 适合框架作者或独立开发者应用 Vercel 的核心特性进行自研集成

Vercel

Build your own web framework - Vercel

Build your own web framework that deploys to edge and serverless infrastructure.