后端Web框架SSR【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址https://gitcode.com/gh_mirrors/vi/vinext点击查看免费下载本文以 .changeset/auto-_vinext_cloudflare_1.0.0-beta.6-8370369.md 中记录的一批 minor 变更为主线结合 vinext/cloudflare 包的源码与官方 README拆解 vinext 在 1.0.0-beta.6 中围绕 Cloudflare CDN 预热CDN warmup、缓存可缓存性探测cacheability probing、两阶段部署two-stage deploy以及静态导出static export所做的系统性加固。读完本文你将理解 vinext 如何把预渲染清单变成“先探测、后准入、再预热、最后切换流量”的 CDN 缓存发布管线并掌握对应命令行参数与源码级判定逻辑。一、这批 changeset 在讲什么从一条条变更看版本主题vinext/cloudflare与vinext同时标记为minor变更共 30 条记录绝大多数以fix(cloudflare)、feat(cache)、fix(cache)为前缀主题高度聚焦在以下四个方向CDN 版本元数据与身份校验如 “finalize CDN version metadata output (#3137)”“verify Worker version IDs during CDN warmup (#3072)”“harden canonical RSC warmup end to end (#3040)”。两阶段部署的拆分与闸门如 “deploy probed manifests in two stages (#3093)”“certify staged cache fills before promotion (#3094)”“configure warmup promotion delay (#3017)”“allow warmup without promotion (#3016)”。缓存准入的探测机制如 “probe Pages Router cacheability (#3098)”“classify and warm static Route Handlers (#3113)”“classify CDN cacheability per concrete route (#3115)”“probe App Page cacheability on staged Workers (#3091)”“preserve Cache Components ownership during probing (#3103)”。静态导出的路由修正如 “support soft navigation in static exports (#3112)”“support trailing-slash static exports (#3081)”“authenticate static file signals (#3077)”。这些条目并非孤立的修修补补而是构成了一条完整的“探测 → 准入 → 预热 → 认证 → 提升promotion”发布链。下一节我们从整体流程讲起。二、两阶段部署为什么预热必须先于流量切换2.1 问题背景在 Cloudflare Workers 上wrangler versions upload上传的是一个“新版本”而非直接生效的流量只有把版本按百分比部署wrangler versions deploy如versionId100%后流量才会切换。如果版本上传后立刻全量切换CDN 缓存还是空的第一批用户请求会全部穿透到源站cold start / cache miss这正是 vinext 引入 CDN 预热的原因。2.2 源码中的两阶段骨架在 packages/cloudflare/src/deploy.ts 中DeployOptions围绕这一流程定义了一组完整参数/** Warm Cloudflares CDN cache by requesting build-discovered paths for the uploaded version */ warmCdnCache?: boolean; /** Explicit production origin to use for CDN discovery, probing, and warming */ warmCdnTarget?: string; /** Maximum number of CDN warmup requests to issue in parallel */ warmCdnConcurrency?: number; /** Per-request CDN warmup timeout in milliseconds */ warmCdnTimeout?: number; /** Number of CDN warmup retries for transient failures */ warmCdnRetries?: number; /** Maximum duration of staged Worker path discovery */ warmCdnDiscoveryTimeout?: number; /** Re-request warmed identities and require reusable CDN hits before promotion */ warmCdnCertify?: boolean; /** Promote the uploaded Worker version to 100% traffic (default: true) */ warmCdnPromote?: boolean; /** Delay between successful warmup and promotion in milliseconds */ warmCdnPromotionDelay?: number; /** Promote even when staged CDN warmup cannot be completed */ dangerouslyPromoteOnCdnWarmError?: boolean;其命令行形态见同一文件的deployArgOptions解析表如下命令行参数默认值说明--experimental-warm-cdn-cachefalse开启两阶段部署的总开关也是--warm-cdn-certify、--warm-cdn-target的前置条件源码会在parseDeployArgs中校验缺一即抛错--warm-cdn-target origin自动发现显式指定用于发现/探测/预热的 HTTPS origin要求无路径、无 query、无凭据、无端口validateCdnWarmTarget--warm-cdn-concurrency n25预热并发数对应DEFAULT_CDN_WARM_CONCURRENCY 25见 cdn-warm.ts--warm-cdn-timeout ms10000单请求超时DEFAULT_CDN_WARM_TIMEOUT_MS 10_000--warm-cdn-retries n1常规预热重试次数--warm-cdn-certifyfalse预热完成后额外发起第二轮请求要求每个计划条目都命中可复用的缓存requireCacheHit才允许提升--warm-cdn-promotion-delay ms15000预热成功到流量提升之间的延迟DEFAULT_CDN_WARM_PROMOTION_DELAY_MS 15_000见 deploy.ts--warm-cdn-no-promote/--no-promotefalse只上传版本并预热不切换到 100% 流量对应warmCdnPromote: !values[no-promote] !values[warm-cdn-no-promote]--dangerously-promote-on-cdn-warm-errorfalse预热失败也强行提升危险开关2.3 “允许预热不提升”与“可配置提升延迟”changeset 中 “feat(cloudflare): allow warmup without promotion (#3016)” 与 “feat(cloudflare): configure warmup promotion delay (#3017)” 对应的正是上面两个参数。默认行为是预热成功后等待15swarmCdnPromotionDelay再执行versions deploy而--warm-cdn-no-promote让用户可以先发布版本、完成预热再由外部编排如灰度系统择机切换流量避免把“预热完成”和“流量切换”耦合在一次 CLI 调用里。三、版本元数据绑定如何证明请求到达了正确的 Worker 版本3.1 为什么需要版本 ID 校验预热最大的隐患是“请求命中了旧版本”如果新版本路由尚未在全球 PoP 传播完毕一次预热请求可能被旧 Worker 处理并写入缓存等于把旧构建的内容当成了新版本的缓存。changeset 中 “verify Worker version IDs during CDN warmup (#3072)”“finalize CDN version metadata output (#3137)”“discover prewarm paths from staged worker (#3090)” 都是在补强这一身份校验。3.2 实现方式cdnAdapter()会生成一个版本元数据绑定默认 binding 名见 packages/cloudflare/src/deploy-config.ts 中DEFAULT_CDN_VERSION_METADATA_BINDING。部署时若检测到实际生效的 Wrangler 配置没有声明该绑定会直接抛错wrangler-version-metadata.ts 给出了明确的错误文案[vinext] Cloudflare CDN warmup requires version metadata binding ..., but the effective Wrangler config ... does not declare version_metadata. Deploy the generated Wrangler config finalized by cdnAdapter(), or add the binding to this effective config and align cdnAdapter({ versionMetadataBinding }) when using a custom name.也就是说默认情况下请直接部署由cdnAdapter()生成的dist/server/wrangler.json它会自动声明该绑定只有确实需要自定义绑定名时才向cdnAdapter({ versionMetadataBinding })传参并保证自定义绑定与 Wrangler 配置一致README.md 的官方说明。绑定建立后预热侧通过VINEXT_CDN_BUILD_ID_HEADER与预期的buildId/rscBuildId比对任何不匹配都会被判定为failed绝不会把旧构建响应误认为预热成功validateBuildIdentity见 cdn-warm.ts。四、缓存准入可缓存性探测Cacheability Probing4.1 从“盲预热”到“探测后再预热”并非所有路由都适合进入 CDN 缓存——带Set-Cookie、Cache-Control: no-store、动态渲染的路由如果被强行预热要么写不进缓存要么污染缓存。beta.6 的核心思路是先探测每个具体路由的可缓存性生成一个 cacheability manifest再只对通过准入的路由做预热。4.2 探测请求的身份设计探测由 packages/cloudflare/src/cacheability-probe.ts 中的probeStagedWorkerCacheability()执行要点如下探测请求带VINEXT_CACHEABILITY_PROBE_HEADER、路由身份头VINEXT_CACHEABILITY_PROBE_ROUTE_HEADER编码了[kind, pattern]以及VINEXT_PRERENDER_SECRET_HEADER密钥确保只有构建方自己能发起探测密钥从dist/server/vinext-server.json的prerenderSecret字段读取readPrerenderSecret缺失时直接报错提示先 rebuild响应是最大 64 KiB 的 JSON envelopeMAX_CACHEABILITY_PROBE_ENVELOPE_BYTES 64 * 1024携带statestatic-candidate/dynamic/probe-failed、scopeidentity/pattern、terminal、rendererStatic等判定字段默认探测并发 25、请求超时 30s、阶段超时 120s、重试 2 次、重试间隔 1s文件顶部的DEFAULT_CACHEABILITY_PROBE_*常量。4.3 三类判定的落点static-candidate该具体路径可缓存写入 manifest 的staticPaths成为后续预热的准入名单dynamicscope 为 pattern整个路由模式被标记为动态模式级剪枝canPrunePattern同一 pattern 下未探测的路径不再逐个请求对应 “classify CDN cacheability per concrete route (#3115)” 的按具体路由分类能力terminal请求在请求阶段即终止如重定向配合requestStageMayTerminate决定是否仍可缓存。manifest 在生成时会做共享路径前缀压缩compactManifestRoutePaths并对总体字节数设上限MAX_CACHEABILITY_MANIFEST_BYTES超出即失败保证发布产物可控。4.4 覆盖 Pages Router 与静态 Route Handlerschangeset 中 “probe Pages Router cacheability (#3098)” 与 “classify and warm static Route Handlers (#3113)” 表明探测不再只针对 App Router 页面Pages Router 的pages-dataJSON 请求身份、以及静态可缓存的 App Route Handler 都纳入了探测与预热计划。在createCdnWarmTargets()cdn-warm.ts中可以看到预热目标按kind分为四类并各自携带正确的请求头目标类型请求头说明htmlAccept: text/htmlApp Router / Pages Router 页面 HTMLpages-dataAccept: application/jsonPages Router 客户端导航用的 JSON 数据rsc-full/rsc-loading-shell规范 RSC 请求头ISR RSC 的完整 payload / loading 边界 payloadapp-routeAccept: */*静态 Route Handler4.5 配对表示的“推测性预热”一个具体路径往往有多个表示HTML、RSC、pages-data。探测只对“代表请求”负责同路径的其他表示speculativeTargets只有在自身最终完成渲染仍可缓存时才被准入见CacheabilityProbeResult的注释 “Paired representations admitted only if their own final warm render remains cacheable”。这对应 “preserve Cache Components ownership during probing (#3103)”——探测过程不改变 Cache Components 的所有权归属。五、预热执行与响应判定5.1 预热队列与传播感知重试warmCdnCache()cdn-warm.ts按并发执行预热请求。若目标带版本覆盖头Cloudflare-Workers-Version-Overrides或标记为传播中的新版本则走“传播感知”路径先给每个 key 一次初始尝试队列完成后再对未解决 key 做一轮重试普通重试上限 1 次、传播重试上限 60 次、间隔 1s直到阶段截止phaseTimeoutMs。每个请求都会读取完整响应体——源码注释明确指出“缓存填充在完整响应体到达前不算完成”防止 Worker 只发响应头就挂起导致部署无限等待。5.2 以 CF-Cache-Status 为权威的准入判定validateCachePolicy()定义了三个层级的缓存策略头优先级Cloudflare-CDN-Cache-ControlCDN-Cache-ControlCache-Control。判定逻辑见 cdn-warm.ts核心如下CF-Cache-Status为HIT/MISS/EXPIRED/REVALIDATED/UPDATING→ 视为已被缓存系统受理返回warmedCF-Cache-Status为BYPASS→ 判定skipped响应通过no-store或Set-Cookie主动退出缓存CF-Cache-Status为DYNAMIC→ 若无可退出头则判定failed设置了Set-Cookie但缺少字段限定field-qualified的缓存策略 → 判定failedhasFieldQualifiedSetCookie会解析privateset-cookie这类写法。特别地Cloudflare-CDN-Cache-Control是在边缘被消费的、不会转发给客户端的策略头因此它可以与下游的no-store或Set-Cookie共存——源码注释明确指出“CF-Cache-Status 才是权威准入结果MISS 意味着响应具备缓存资格而响应期拒绝会被报告为 BYPASS”。5.3 可选认证--warm-cdn-certify默认流程每个准入身份只做一次填充请求。--warm-cdn-certify开启后预热完成后会再发一轮仅取头的请求并要求每个计划条目都必须拿到可复用的缓存状态REUSABLE_CF_CACHE_STATUSES { HIT, REVALIDATED, UPDATING }见 cdn-warm.ts——MISS不再被接受因为 MISS 只代表“具备资格”不代表“已经可复用”。这对应 “certify staged cache fills before promotion (#3094)”。六、部署后的就绪检查Readiness预热完成后真正提升流量之前还需要确认新版本已经“就绪”即路由传播到可以稳定服务。waitForCdnWarmTargetReadiness()cdn-warm.ts承担这一职责关键默认值如下常量默认值含义DEFAULT_STAGED_READINESS_RETRIES60就绪探测最大尝试次数DEFAULT_STAGED_READINESS_INTERVAL_MS1000探测间隔DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS120000就绪阶段总截止时间DEFAULT_STAGED_READINESS_SUCCESSES6需要连续成功的探测次数requiredConsecutiveSuccesses就绪探测会从预热计划中选择代表路径优先 RSC其次 HTML、pages-data、app-route并优先使用预渲染就绪端点VINEXT_PRERENDER_READINESS_PATHPOST 密钥认证请求带Cache-Control: no-cache与Pragma: no-cache绕过缓存且每次请求携带独立随机 ID__vinext_cdn_warm_readinessquery 参数。只有连续 6 次成功且返回的 build 身份与预期一致才返回{ ready: true }随后才进入提升流程——这正是 “harden post-deploy readiness checks (#3136)” 与 “complete warmup response and promotion contracts (#3046)” 所加固的契约。七、配套的静态导出修复与 CDN 管线并列beta.6 还修补了静态导出static export场景的三处问题“support soft navigation in static exports (#3112)”静态导出下客户端软导航soft navigation需要正确的请求身份避免刷新/回退时触发整页加载“support trailing-slash static exports (#3081)”trailingSlash: true配置下预热路径会通过normalizePathTrailingSlash统一规范化applyWarmPathConfig()cdn-warm.ts同时处理basePath前缀确保路径与构建产物一致“authenticate static file signals (#3077)”静态文件的请求信号在发布与缓存流程中需要被认证防止绕过缓存准入的请求污染缓存。八、官方推荐的接入方式根据 packages/cloudflare/README.md启用这套体系只需两步配置 CDN 适配器可选但有条件——cdnAdapter()会自动生成两个 Worker 入口默认入口关闭缓存用于中间件与请求时路由VinextCachedResponse延迟加载带 Workers Cache 的渲染阶段import { cdnAdapter } from vinext/cloudflare/cache/cdn-adapter; vinext({ cache: { cdn: cdnAdapter() } });部署时开启两阶段流程npx vinext-cloudflare deploy --experimental-warm-cdn-cache官方 README 明确指出生成的版本元数据绑定让预热可以证明每次 discovery、probe、fill 请求都到达了上传的 Worker 版本默认流程每个准入身份做一次最终填充请求只有需要额外认证时才追加--warm-cdn-certify。九、小结beta.6 的发布管线全貌将本 changeset 的所有条目串起来可以得到 vinext 1.0.0-beta.6 在 Cloudflare 上的完整发布管线build预渲染路径清单 prerender manifest 版本元数据 → versions upload上传新版本不切换流量 → 路径发现--warm-cdn-discovery-*从 staged Worker 发现预热路径 → 可缓存性探测cacheability probing按具体路由分类生成 manifest → 分两阶段部署 probed manifest#3093 → CDN 预热并发 25CF-Cache-Status 准入判定 → 可选 certify 认证--warm-cdn-certify要求可复用缓存命中 → 就绪检查连续 6 次成功 版本身份校验 → 等待 promotion 延迟默认 15s后 versions deploy 切换流量 或 --warm-cdn-no-promote 只预热不切换每一道闸门都有对应的源码常量、命令行参数与响应判定逻辑本文引用的实现均可在仓库的 packages/cloudflare/src 下继续追读预热核心在 cdn-warm.ts探测在 cacheability-probe.ts部署编排在 deploy.ts版本元数据绑定约束在 wrangler-version-metadata.ts。配套的端到端验证可参考 cloudflare-cdn-warm.test.ts 与 cloudflare-cdn-warm-deploy.test.ts 等测试用例。赞分享后端Web框架SSR【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址https://gitcode.com/gh_mirrors/vi/vinext点击查看免费下载相关推荐Android-DFU-Library与Kotlin集成教程现代化蓝牙固件更新方案Android DFU Library与Kotlin集成教程现代化蓝牙固件更新方案 想要为你的Android应用添加蓝牙设备固件更新功能吗Android D后端Web框架SSRvinext 1.0.0-beta.2 版本变更集解读Cloudflare KV 缓存键限长、Next.js 兼容类型与多路由修复批次vinext 1.0.0 beta.2 版本变更集解读Cloudflare KV 缓存键限长、Next.js 兼容类型与多路由修复批次 本文以 CI 自动生成后端Web框架SSRRust 编译错误 E0566conflicting representation hints冲突的 [repr] 表示提示解析Rust 编译错误 E0566conflicting representation hints冲突的 repr 表示提示解析 本文围绕 rustc 错误代后端Web框架SSR上一篇smallnest/rpcx网络模型解析IO多路复用与协程池设计下一篇Conferences.digital的现代化UI设计macOS原生控件与自定义视图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
