企业官网建设流程全解析

• 后端
• Web框架
• SSR

@vinext/cloudflare 是 vinext（Vite plugin 重新实现 Next.js API 的部署方案）在 Cloudflare Workers 上的官方配套包，提供 KV 数据缓存、Workers Cache CDN 缓存、Workers Response Store 与 Cloudflare Images 四类运行时适配器，以及一条vinext-cloudflare deploy部署 CLI。本文以 packages/cloudflare/README.md 为主体，结合 packages/cloudflare/src 下的源码与 examples/response-store-demo 示例工程，完整讲解每个适配器的配置方式、底层实现原理与生产级部署流程。读完你可以为任意 vinext 项目选配缓存后端、在 Vite 配置中声明适配器、并掌握含 CDN 预热的双阶段部署。

一、包定位：vinext 的 Cloudflare 专属运行时适配层

在 vinext 的架构里，核心包负责把 Next.js 的页面渲染、ISR、next/image等能力重现在任意平台上，而“缓存存哪里、图片怎么变换”这类平台强相关的能力由适配器（adapter）完成。@vinext/cloudflare 正是这一层：它不参与业务渲染，而是把 vinext 的数据缓存（data cache）、页面级缓存（page-level cache）和图片优化接到 Cloudflare 的原生基础设施上。

从 package.json 可以看到，包的产物通过exports字段暴露了两个子路径族：

• ./cache/*→dist/cache/*，包含全部缓存适配器；
• ./images/*→dist/images/*，包含图片优化器。

同时它声明了bin字段（@vinext/cloudflare与vinext-cloudflare均指向dist/cli.js），提供deploy子命令，用于把构建产物直接部署到 Cloudflare Workers。包依赖@cloudflare/workers-response-store（Response Store 的实现），peer 依赖vinext，要求 Node.js >= 22。

该包当前共提供四个核心适配器，对应 README 的四条主线：

二、快速上手：在 Vite 配置中声明适配器

所有适配器都是“配置期构造器”：它们可以在vite.config.ts中安全调用，返回一个可序列化的描述符，真正的运行时实例由生成的virtual:vinext-cache-adapters注册表在首个请求时按需实例化。以 KV 数据缓存加 Cloudflare Images 的典型组合为例：

// vite.config.ts import { kvDataAdapter } from "@vinext/cloudflare/cache/kv-data-adapter"; import { imagesOptimizer } from "@vinext/cloudflare/images/images-optimizer"; export default defineConfig({ plugins: [ vinext({ cache: { data: kvDataAdapter(), // KV-backed data cache (binding: VINEXT_KV_CACHE) }, images: { optimizer: imagesOptimizer() }, // Cloudflare Images binding: IMAGES }), cloudflare(), ], });

配合cloudflare()插件（vite-plugin-cloudflare）一起使用。这里kvDataAdapter()对应数据缓存（fetch缓存、"use cache"、unstable_cache的统一底层），imagesOptimizer()对应图片变换。

为什么必须要求适配器是“配置期可序列化”的？看 images-optimizer.ts 的实现就明白了：它只做两件事——校验binding参数类型，然后返回{ adapter: fileURLToPath(import.meta.resolve("./images-optimizer.runtime.js")), options }。fileURLToPath(import.meta.resolve(...))把运行时工厂的绝对路径解析出来交给构建流程，配置期绝不实例化优化器、也绝不读取 binding，因此 Vite 配置可以被安全地执行和序列化。kvDataAdapter、cdnAdapter、responseStoreAdapter全部遵循同一模式。

三、数据缓存：kvDataAdapter 与 KV 后端

3.1 前置条件：在 Wrangler 配置中声明 KV namespace

kvDataAdapter()需要一个已存在的 KV namespace。运行时工厂在构造KVCacheHandler时从 Worker 的env读取绑定（默认名VINEXT_KV_CACHE），找不到会直接抛错并提示补全配置。对应的 kv-data-adapter.ts 给出了 Wrangler 配置写法：

// wrangler.jsonc { "kv_namespaces": [ { "binding": "VINEXT_KV_CACHE", "id": "<your-kv-namespace-id>" } ] }

3.2 选项参数一览

kvDataAdapter(options?)接受以下可选参数（定义见 kv-data-adapter.ts，默认值均有源码注释佐证）：

其中binding若传了非字符串会抛出TypeError（源码第 48-50 行有显式校验）。

3.3 底层原理：KVCacheHandler 如何工作

kvDataAdapter()返回的描述符指向 kv-data-adapter.runtime.ts，其默认导出是createKvDataCacheAdapter工厂：请求到达时从env[binding]读取 KV namespace，构造KVCacheHandler实例。该类实现了 vinext 的CacheHandler接口，核心逻辑值得展开：

序列化策略。KV 只能存字符串，而缓存值里的rscData（APP_PAGE）、body（APP_ROUTE）、buffer（IMAGE）都是ArrayBuffer。运行时先把这些字段用 base64 编码（serializeForJSON），读回时再做安全解码恢复（restoreArrayBuffers）。任何 base64 校验失败都视为损坏条目，静默当作 miss 并后台删除，绝不把脏数据交给上层（对应源码第 278-289 行与base64ToArrayBuffer的字母表预校验）。

TTL 与“陈旧”解耦。这是最容易踩坑的设计：KV 的物理过期（expirationTtl）与“什么时候该后台重新生成”（revalidateAt）是两回事。revalidateAt存进 JSON 而非依赖 KV 驱逐——如果让 KV TTL 跟着 revalidate 窗口走，一个revalidate=5的页面在 50 秒无流量后就会被物理驱逐，下一次请求被迫阻塞等待全新渲染，而不是立刻返回 stale 内容。因此运行时固定把条目保留 30 天（ttlSeconds默认值），活跃页面由后台再验证不断覆盖键（对应源码第 505-519 行注释）。

基于 tag 的失效与路径失效。revalidateTag()为每个合法 tag 写一个“失效标记”（时间戳）键；revalidatePath()走的是revalidateByPathPrefix()——它利用 KVlist的 metadata 字段发现 entry 携带的 tags（每个 entry 写入时把 tags 序列化进 KV metadata，上限 1024 字节，超出则优雅降级跳过），从而把前缀失效的复杂度降到 O(list_pages) 而不是 O(entries × get)。标签校验规则也很严格：长度上限 256、拒绝控制字符与:（因为:是内部 key 分隔符，放行用户 tag 会造成 key 歧义）、允许/（revalidatePath依赖/posts/hello这类路径 tag）。

软标签与批量读取优化。get()里“soft tags”（读之前就已知的 tag）和 entry 自带 tags 被分批读取：批量get()受 Cloudflare 限制每次最多 100 个键，运行时按 100 分块并发（KV_BULK_GET_LIMIT）。进程内_tagCache用 5 秒 TTL 兜底，避免高频请求重复读同一批标记；同时用单调递增的order防止并发读回写旧值（源码第 381-392 行）。entryCacheTtlSeconds只作用于 entry 读取、绝不作用于 tag 标记——因为revalidateTag()写入的标记若被某个 colo 长时间缓存，发布后的失效会被该 colo 掩盖；失效窗口始终被控制在tagCacheTtlMs+ KV 默认 60s 以内。

从测试与 shim 的角度看，这类 handler 被注册进vinext/shims/cache的缓存接口（可参考 packages/vinext/src/shims/cache.ts 与 cache-adapters-virtual.ts 的注册机制）。

四、页面级 CDN 缓存：cdnAdapter 与 Workers Cache

4.1 双入口设计：缓存命中不启动应用

cdnAdapter()是可选适配器，负责把页面级 ISR 的对外提供（serving）与再验证（revalidation）交给 Cloudflare Workers Cache。它与数据缓存的关键区别在 cdn-adapter.ts 的注释里说得很清楚：数据缓存把条目存进持久存储、自己判定 HIT/STALE；而 CDN 适配器把“对外提供”委托给 Workers Cache 上的一个命名入口。

配置后，Cloudflare 构建会产出两个 Worker entrypoint：

• 默认入口：运行 middleware 与请求期路由，缓存关闭；
• VinextCachedResponse：懒加载渲染阶段（render stage），Workers Cache 开启。

这些设置会被写入生成的dist/server/wrangler.json。因此 README 特别强调：不要在源配置（source config）的默认入口上手动开启 Workers Cache——生成的配置才是权威来源。同时生成配置还会声明“版本元数据绑定”（version metadata binding），供分阶段预热（staged warmup）使用。

import { cdnAdapter } from "@vinext/cloudflare/cache/cdn-adapter"; vinext({ cache: { cdn: cdnAdapter() } });

4.2 版本元数据绑定与响应入口

生成的版本元数据绑定用于让 staged warmup 证明：每一个 discovery、probe、fill 请求都真实命中了已上传的 Worker 版本。默认绑定名是CF_VERSION_METADATA（DEFAULT_CDN_VERSION_METADATA_BINDING），只有部署确实需要自定义绑定名时才给cdnAdapter()传versionMetadataBinding（且必须是非空字符串，否则抛TypeError，见 cdn-adapter.ts）。

适配器的output字段（源码第 52-80 行）揭示了双入口的落法：它只对virtual:cloudflare/worker-entry做transformHostEntry注入，追加export { VinextCachedResponse, VinextUncachedResponse } from <worker-entry>；finalizeBuildOutput负责在构建收尾时把 Workers Cache 与版本元数据绑定写进生成的 Wrangler 配置，并以multi-stage类型参与构建。VinextUncachedResponse保持缓存关闭，让 bypass 与 probe 渲染不经过缓存网关。

响应入口会把完整传输身份（transport identity）哈希进 Workers Cache URL——这是独立于 zone Cache Rules 的。也就是说，即使 zone 层面配置了缓存的 key 规则，不同的 query 与表示变体（representation variants）在 Workers Cache 中也不会互相碰撞（README 与源码第 31-33 行注释相互印证）。

4.3 CDN 预热与两阶段部署

cdnAdapter()通常与部署期的--experimental-warm-cdn-cache配合使用：

• 默认流程：每个被准入（admitted）的身份只发一个最终的 fill 请求；
• 追加--warm-cdn-certify：开启一个可选的头-only 二次请求，要求每一个计划内的条目在提升（promotion）前都必须被证明可复用。

关于这些 CLI 参数与 Workers Cache 的 tiered caching 行为，详见第七节的完整参数表。

五、统一缓存后端：responseStoreAdapter 与 Workers Response Store

responseStoreAdapter()是二合一方案：它同时替换cdnAdapter()和kvDataAdapter()，用 Workers Response Store 同时承担响应缓存与数据缓存。定义见 response-store-adapter.ts，它返回{ cdn: {...}, data: {...} }两个描述符，分别挂在vinext()的cache.cdn与cache.data上。

5.1 模式一：service-binding（默认，独立缓存 Worker）

默认模式把存储放进独立的缓存 Worker，应用 Worker 通过RESPONSE_STOREservice binding 访问它。vinext init会生成两份并列的源配置：

• wrangler.jsonc：应用 Worker 配置；
• wrangler.response-store.jsonc：缓存 Worker 配置。

后者直接指向已安装的@cloudflare/workers-response-store实现（main为./node_modules/@cloudflare/workers-response-store/dist/service.js），并拥有自己的 R2 bucket、SQLite Durable Object、Worker 名称与缓存设置。示例见 examples/response-store-demo/wrangler.response-store.jsonc：R2 bucketCACHE_BODIES、SQLite Durable ObjectCacheMetadata、cache-enabled 入口ResponseStoreBinding都在这一份配置里。

对应的应用配置 examples/response-store-demo/wrangler.jsonc 则通过services字段把RESPONSE_STOREbinding 指向名为response-store-demo-response-store的缓存 Worker，并声明version_metadata（CF_VERSION_METADATA）。

两个 Worker 刻意分开部署：缓存 Worker 的包或配置变更时先部署它，然后正常部署应用：

npx wrangler deploy --config wrangler.response-store.jsonc npx @vinext/cloudflare deploy

需要强调的是：vinext-cloudflare deploy永远不会创建、改写或部署 Response Store Worker（README 原文承诺，也与 CLI 的实现一致——deploy 命令只处理应用本身）。要调整缓存 Worker 名称、R2 bucket 名称，直接编辑wrangler.response-store.jsonc，同时保持应用配置里的 service binding 与缓存 Worker 名称对齐。

5.2 元数据分片：shards

元数据分片（metadata sharding）是可选能力，两种部署模式都支持：

vinext({ cache: responseStoreAdapter({ shards: 16 }) });

开启后，键（keys）仍然固定钉在同一个分片上（保证单键一致性），而 tag/path 的变更（mutations）会扇出到所有分片。不传shards则保留原来的单一元数据 Durable Object。源码对shards有严格校验：必须是大于 1 的安全整数，否则抛TypeError（response-store-adapter.ts）。

5.3 位置提示：locationHint

要让新建的元数据 Durable Object 靠近稳定的流量与 R2 区域，可以传 Cloudflare location hint：

vinext({ cache: responseStoreAdapter({ locationHint: "weur" }) });

合法值由源码中的RESPONSE_STORE_LOCATION_HINTS表限定（response-store-adapter.ts）：afr、apac、apac-ne、apac-se、eeur、enam、me、oc、sam、weur、wnam。传入不支持的字符串同样抛TypeError。

注意事项（README 原话，务必遵守）：

• hint 是 best-effort，且只影响每个 Durable Object首次创建的位置；
• 修改 hint不会迁移已存在的对象；
• 应把修改 hint 视为一次“缓存冷却”（cache-cold）的部署变更，并让 hint 与 R2 bucket 所在区域保持一致。

5.4 模式二：self-contained（自包含模式）

如果希望把存储与缓存入口和应用一起部署（不拆分第二个 Worker），使用自包含模式：

import { responseStoreAdapter } from "@vinext/cloudflare/cache/response-store-adapter"; vinext({ cache: responseStoreAdapter({ mode: "self-contained" }) });

在此模式下，vinext init把所需的 R2、SQLite Durable Object、Workers Cache 入口和版本元数据配置全部放进单个wrangler.jsonc，无需第二份 Wrangler 配置。示例可见 examples/response-store-demo/wrangler.self-contained.jsonc：一个文件内同时包含 assets、cache.enabled、exports（default /ResponseStoreBinding/CacheMetadata）、r2_buckets、durable_objects与version_metadata。源码层面，mode决定运行时工厂文件（response-store-adapter.self-contained.worker.js或response-store-adapter.service-binding.worker.js）以及注入的入口集合——自包含模式导出CacheMetadata, ResponseStoreBinding, ResponseStoreRevalidator，而 service-binding 模式只导出ResponseStoreClient, ResponseStoreRevalidator（response-store-adapter.ts）。mode传未知值会抛Error（源码第 47-49 行）。

六、图片优化：imagesOptimizer 与 Cloudflare Images

imagesOptimizer()把next/image的变换请求（/_next/image）接到 Cloudflare Images binding，在边缘完成 resize、格式协商（AVIF/WebP）与质量变换——无需自定义 Worker 入口（images-optimizer.ts 的注释明确写了这一点）。

用法（与 KV 数据缓存组合的完整示例已在第二节给出）：

import { imagesOptimizer } from "@vinext/cloudflare/images/images-optimizer"; vinext({ images: { optimizer: imagesOptimizer() } });

唯一可配置项是binding（Cloudflare Images binding 在 Workerenv上的名字），默认"IMAGES"。其运行时实现位于 images-optimizer.runtime.ts，同样遵循“配置期构造器返回可序列化描述符 + 运行时工厂按需实例化”的模式，binding非字符串时抛TypeError。

七、部署：vinext-cloudflare deploy 全参数解析

7.1 基本用法

项目构建完成后，用包自带的 CLI 一键部署：

npx @vinext/cloudflare deploy

Vite+ 环境下还可以用：

vpx @vinext/cloudflare deploy # 或运行本地安装的 bin vp exec vinext-cloudflare deploy

命令入口在 cli.ts：解析deploy子命令并把全部参数透传给deploy()（来自 deploy.ts）。--version/-v打印vinext-cloudflare v<version>，--help/-h打印完整帮助（文案见 deploy-help.ts）。

7.2 基础选项

7.3 CDN 预热选项（配合 cdnAdapter）

7.4 流量感知预热（experimental）

针对流量选择预热路由的选项组：

流量感知预热使用 Cloudflare zone analytics 挑选流量最高的路由，再喂进与--experimental-warm-cdn-cache相同的 staged 预热流程。它要求自定义域名以及具备Zone Analytics 读取权限的CLOUDFLARE_API_TOKEN。另外，Workers Cache 自动启用 tiered caching，因此预热过的条目在缓存传播后可以被预热请求所达数据中心之外的边缘复用，但部署不会等待每个边缘位置都填满。

7.5 常用组合示例

# 构建并部署到生产 npx @vinext/cloudflare deploy # Vite+ 环境 vpx @vinext/cloudflare deploy # 部署到 preview / 指定环境 vinext-cloudflare deploy --preview vinext-cloudflare deploy --env staging # 使用生成的 Wrangler 配置部署（cdnAdapter 场景） vinext-cloudflare deploy --config dist/server/wrangler.json # 只校验不部署 vinext-cloudflare deploy --dry-run # 上传版本但不改流量 vinext-cloudflare deploy --no-promote # 两阶段 CDN 预热部署 vinext-cloudflare deploy --experimental-warm-cdn-cache vinext-cloudflare deploy --experimental-warm-cdn-cache --warm-cdn-target https://example.com # 流量感知预热 vinext-cloudflare deploy --experimental-traffic-aware-warm-cache --traffic-aware-coverage 95

八、选型建议与示例工程

8.1 三个缓存方案怎么选

从 README 与源码可以归纳出清晰的取舍逻辑：

• kvDataAdapter：轻量起点。一个 KV namespace 即可支撑数据缓存，适合缓存量可控、不需要页面级 CDN 网关的场景；若要页面级 ISR 对外缓存，需叠加cdnAdapter()。
• cdnAdapter：页面级 ISR 的 CDN 化提供。与kvDataAdapter互补而非替代，配合--experimental-warm-cdn-cache做缓存预热与版本化部署。
• responseStoreAdapter：替代前两者（README 原文：“replaces bothcdnAdapter()andkvDataAdapter()”）。一份配置同时解决数据缓存与响应缓存；有独立缓存 Worker（service-binding）与单 Worker（self-contained）两种形态，并支持分片与区域提示。适合希望减少运维面、把缓存基础设施交给 Cloudflare Response Store 的项目。

8.2 参考示例：response-store-demo

仓库中的 examples/response-store-demo 是围绕 Response Store 三种形态的完整示例工程，包含README.md与四份 Wrangler 配置，可作为实操蓝本：

• wrangler.jsonc：应用 Worker（service-binding 模式），RESPONSE_STOREservice binding 指向独立缓存 Worker，version_metadata绑定CF_VERSION_METADATA；
• wrangler.response-store.jsonc：缓存 Worker，持有 R2 bucket、SQLite Durable Object 与缓存入口；
• wrangler.self-contained.jsonc：self-contained 单文件配置；
• wrangler.kv.jsonc：KV 数据缓存形态的参考配置。

@vinext/cloudflare的测试脚本（package.json 的test）也以VINEXT_RESPONSE_STORE_MODE=self-contained与VINEXT_RESPONSE_STORE_LOCATION_HINT=weur/wnam组合实际构建 response-store-demo，验证两种模式与位置提示在真实构建链路中的行为——需要调试或验证配置时可以直接复用这条命令。

结语

@vinext/cloudflare 把 vinext 的缓存与图片能力完整地映射到 Cloudflare Workers 的原生基础设施上：KV 数据缓存、Workers Cache 的 CDN 化页面缓存、Response Store 的统一缓存后端，以及 Cloudflare Images 的图片变换，全部通过声明式适配器接入vinext()插件，并配有覆盖基础部署、环境部署、CDN 预热与流量感知预热的单命令 CLI。无论是从零起步的 KV 方案，还是追求统一缓存与最小运维面的 Response Store 方案，本文给出的配置示例、参数表与源码级原理分析都可以直接指导落地。下一步建议对照 examples/response-store-demo 的配置跑通一次vinext init与npx @vinext/cloudflare deploy，再按需引入cdnAdapter与预热参数做生产优化。

• 后端
• Web框架
• SSR