vinext实战案例集Hacker News、Nextra文档站跑在Workers上的全过程【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址: https://gitcode.com/gh_mirrors/vi/vinextvinext是一个 Vite 插件它重新实现了整套 Next.js 的 API 表面App Router、next/link、RSC 流式渲染、ISR 等让你无需 Next.js 运行时就能把 React 应用直接部署到 Cloudflare Workers 上。本文将完整复盘仓库中两个经典实战案例一个功能完整的Hacker News 克隆站React Server Components 动态路由和一个Nextra 风格 MDX 文档站从项目结构、关键配置到部署 Workers 的全过程新手也能照着做。一、先搞懂vinext 到底做了什么 你熟悉的 Next.js 能力vinext 中的对应实现App Router / RSC内置路由 服务端组件流式输出next/link、useRouter等全部以 shim 方式提供ISR / 缓存可选 CDN 缓存与 KV 数据缓存适配器部署目标任意支持 Worker 的环境默认面向 Cloudflare Workers一句话理解写 Next.js 风格的代码跑在 Vite 上部署到 Workers。二、案例一Hacker News 克隆站React Server Components案例位置examples/hackernews/这是一个 Hacker News 风格的新闻聚合站首页展示热帖列表点进item/[id]查看评论区支持路由级骨架屏、错误页与 404 页。2.1 项目结构速览 ️app/news/[page]/page.tsx — 列表页动态page参数app/item/[id]/(comments)/page.tsx — 评论区路由app/item/[id]/(comments)/loading.tsx — 路由级加载骨架components/server-info.jsx — 服务端组件示例worker/index.ts — Cloudflare Worker 入口2.2 关键配置三行插件搞定一切打开 vite.config.ts整个构建只依赖三个插件vinext()—— 提供 Next.js 兼容层、路由与 RSCcloudflare(...)—— 把 RSC 环境编译到 workerd 运行时并挂载ssr子环境。这正是 vinext 零 Next.js 依赖的核心不需要next buildvp buildVite Plus即可产出 Workers 产物。2.3 Worker 入口RSC 请求如何被接管worker/index.ts 展示了最简洁的接入方式通过import.meta.viteRsc.loadModule(rsc, index)加载 RSC 处理器返回Response则直接透传返回null则回 404入口处还做了协议相对 URL//evil.com的开放重定向防护细节拉满。2.4 路由与数据完全是 Next.js 的写法列表页 app/news/[page]/page.tsx 使用了generateStaticParams预生成第 1 页其余页走动态渲染dynamicParams true——和官方 Next.js 的语义完全一致。首页 301 到/news/1则沿用 Next.js 风格的rewrites配置见 next.config.js。2.5 部署到 Workerswrangler.jsonc 只有 10 行main指向vinext/server/app-router-entry预构建好的入口compatibility_flags开启nodejs_compat。构建并部署只需vp build npx wrangler deploy三、案例二Nextra 风格 MDX 文档站案例位置examples/nextra-docs-template/文档站是 vinext 生态的另一块拼图MDX 内容 侧边栏导航 服务端组件计数器全部跑在 Workers 上。3.1 与原版 Nextra 模板的差异 维度原版 Nextra 模板vinext 版本构建工具Next.js CLIVitevp build路由Pages RouterApp RouterMDX 编译Nextra webpack 插件mdx-js/rollupnext/*导入原生支持vinext shim详细说明可参考 app/content/index.mdx。3.2 配置差异只有一个多了 MDX 插件对比 vite.config.ts第一个插件mdx()负责把.mdx文件编译成 React 组件其后依然是熟悉的vinext()cloudflare()组合。也就是说接入一个 MDX 文档站只需要在插件链里多挂一个 Rollup 插件其余全部交给 vinext。3.3 内容与布局app/page.tsx 只有一行直接渲染content/index.mdxapp/layout.tsx 用next/linkvinext shim 提供搭建侧边栏导航树components/counters.tsx 是一个服务端组件计数器演示 RSC 场景下的状态更新。3.4 部署wrangler.jsonc 中main指向vinext/server/fetch-handler——比 Hacker News 案例更精简的入口适合纯 SSR 应用。同样vp buildwrangler deploy两步完成。四、进阶彩蛋让页面缓存到 Workers 边缘 ⚡如果你希望文档站/列表页享受ISR增量静态再生可以看 examples/workers-cache/ 这个演示它的 README 是理解 vinext 缓存体系的最好材料cdnAdapter()—— 页面级 ISR 走 Cloudflare Workers Cache边缘直接吸收 HIT/STALE 流量后台再验证kvDataAdapter()—— 用 Workers KV 承接use cache/ fetch 数据缓存。接线方式见 vite.config.ts在vinext({ cache: { cdn, data } })里声明两个适配器即可平台侧则在 wrangler.jsonc 中开启cache并绑定VINEXT_KV_CACHE命名空间。之后revalidateTag()/revalidatePath()会自动扇出到缓存清除不需要手动注册任何运行时。五、通用部署清单两个案例通用✅本地开发vp dev基于 miniflare 模拟 Workers 环境KV 等绑定本地可用构建vp build产出dist客户端静态资源 worker 产物部署npx wrangler deploywrangler.jsonc已指明 vinext 预构建入口验证部署后可用preview_urls拿到预览地址直接访问。 小技巧Hacker News 案例的wrangler.jsonc用的是app-router-entry含静态资源接管Nextra 案例用的是fetch-handler纯请求入口。如果你的项目有静态资源目录推荐前者。六、写在最后这两个案例覆盖了 vinext 的两大典型场景动态内容站Hacker NewsRSC、动态路由、路由组、骨架屏、404/错误页一应俱全内容型文档站NextraMDX 生态无缝接入next/*全部由 shim 兜底。对新手来说最快的上手路径是复制 examples/hackernews/ 或 examples/nextra-docs-template/ 的目录结构把vinext()cloudflare()两个插件放进自己的 Vite 项目再配一份 10 行以内的wrangler.jsonc——Next.js 的写法Vite 的速度Workers 的边缘部署三全其美。【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址: https://gitcode.com/gh_mirrors/vi/vinext创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考