如何参与vinext开发AI驱动的贡献工作流与CI流程完整指南【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址: https://gitcode.com/gh_mirrors/vi/vinextvinext 是一个用 Vite 重新实现 Next.js API 的开源插件让开发者可以把现有 Next.js 应用一键部署到 Cloudflare Workers。它的特别之处在于几乎每一行代码都由 AI 编写每个 Pull Request 也由 AI 智能体创建和审查。因此如何参与 vinext 开发这件事本身就与众不同——你几乎一定要借助 AI 工具才能在这个仓库里高效干活。这篇指南将从环境搭建、项目结构、AI 贡献工作流到完整的 CI 流程与 AI 代码审查带你走完从新手到合并 PR 的全过程。 为什么 vinext 的参与方式与众不同vinext 诞生于一次把 AI 推到极限的实验。维护者在 CONTRIBUTING.md 里开门见山几乎每一行代码都由 AI 编写每个 PR 都由 AI 智能体创建和审查。我们欢迎人类贡献但想在这个仓库里玩得开心你就得用上 AI。这意味着两件事别裸手硬写带着 AI 编码工具如 Claude Code、OpenCode、Cursor进入项目让它帮你读源码、跑测试、定位 bug。审查也会由 AI 完成你的提交需要通过与 AI 的多轮反馈迭代。官方推荐的 AI 配置在 CONTRIBUTING.md 中说明用于审查的智能体分为轻量级和深度级两档稍后会细讲。 一键上手克隆仓库与环境搭建如果你想从源码而非 npm 包参与开发按 README.md 的Local setup章节操作# 克隆 vinext 仓库 git clone https://gitcode.com/gh_mirrors/vi/vinext cd vinext pnpm install pnpm run build这条命令会把 vinext 主包构建到packages/vinext/dist/。日常开发时可以用pnpm --filter vinext run dev实现改动后自动重建省去手动编译的等待。 仓库采用 pnpm workspace 管理主包代码位于packages/vinext/务必保持锁定文件冻结frozen lockfile避免意外引入未审查的依赖。 3 分钟读懂项目结构在动手前先建立全局认知。核心文件一览摘自 AGENTS.md目录 / 文件作用packages/vinext/src/index.ts主 Vite 插件解析next/*导入、生成虚拟模块packages/vinext/src/shims/对next/link、next/navigation等模块的重新实现packages/vinext/src/server/SSR 处理器、ISR、中间件逻辑tests/*.test.tsVitest 单元测试tests/fixtures/测试用示例应用如pages-basic、app-basictests/e2e/Playwright 浏览器级 E2E 测试examples/面向用户演示的移植应用vinext 的核心目标是精确复刻 Next.js 的行为。当你需要理解某个特性时架构要点RSC 与 SSR 是两个独立的 Vite 环境、请求执行顺序等都记录在 AGENTS.md 里这是给 AI 和自己看的地图。上图展示了 vinext 中可缓存路由的服务端缓存与预渲染机制这正是贡献者最常接触的缓存 / ISR 领域之一。 AI 驱动的贡献工作流这是 vinext 最精髓的部分。无论是加功能还是修 bug维护者的标准动作都是先让 AI 对齐 Next.js 的真实行为再动手。1. 加新功能摘自 AGENTS.md 的Adding a New Feature确认 Next.js 是否已有该特性弄清期望行为搜索 Next.js 测试套件找到相关测试用例先写测试再在shims/或server/里实现必要时为tests/fixtures/添加测试页面2. 修 bug永远先验证 Next.js 的行为。维护者反复强调跳过这一步曾导致多次静默的行为差异。正确的排查链路是查 Next.js 测试 → 查相关讨论 → 读 Next.js 源码 → 在 PR 中记录你的判断依据。3. 本地快速检索技巧。建议把 Next.js 仓库克隆到本地.nextjs-ref目录用rgripgrep做高速源码与测试搜索比在线搜索更可靠。⚠️ 一条铁律永远不要用--no-frozen-lockfile自行安装依赖。这会绕过锁定文件的完整性校验存在供应链风险。若确需改动锁定文件应交由人工执行。✅ 提交前必做清单测试与静态检查在打开 PR 之前CONTRIBUTING.md 给出了四步清单而 AGENTS.md 提供了更细的日常命令优先使用vpvp check tests/app-router.test.ts # 对改动文件做格式化、lint、类型检查 vp test run tests/app-router.test.ts # 只跑单个测试文件秒级 vp test run tests/app-router.test.ts -t route handler # 按名称过滤 pnpm run check # 全量静态检查一个高频原则只跑目标测试不跑全量套件。全量 Vitest 约需 2 分钟串行执行开发期间反复跑会浪费时间。根据你改动的模块选择对应测试即可改动位置应运行的测试某个 shimshims/*.tstests/shims.test.ts 对应 shim 测试路由routing/*.tstests/routing.test.ts、tests/route-sorting.test.ts缓存 / ISRtests/isr-cache.test.ts、tests/fetch-cache.test.ts构建 / 部署tests/deploy.test.tsNext.js 兼容特性tests/nextjs-compat/下相关文件 把全量回归留给 CI。CI 会在每个 PR 上运行完整套件本地只需守住你改动的那一小片。 深入 CI你的 PR 会经历哪些关卡vinext 的 CI 分为安全检查与部署预览两层兼顾了开源安全与快速反馈。工作流定义在.github/workflows/目录下。安全检查ci.yml对所有 PR 运行核心任务包括Check构建插件、运行vp check与knip、对脚本做 Bash 语法检查Vitest 单元测试按 3 个分片并行执行Vitest 集成测试按 10 个分片执行并按耗时清单自动平衡负载Playwright E2E覆盖 Pages Router开发生产、App Router开发以及在 Workers 上的两种路由create-next-app 冒烟测试在 Ubuntu 与 Windows 上从脚手架到vinext init走一遍真实迁移分片机制由scripts/ci-integration-shard.mjs与 scripts/ci-integration-timings.json 驱动能根据真实 CI 耗时动态再平衡保证各分片耗时均衡。部署预览deploy-examples.yml仅主仓库分支自动运行对 fork PR 默认整体跳过以保护密钥安全贡献者可在 PR 下评论/deploy-preview由维护者触发构建全部示例、部署预览、运行冒烟测试并回贴预览地址安全设计的三条红线摘自 AGENTS.mdci.yml永不使用密钥因为它要运行来自 fork 的不可信代码部署工作流必须对 fork PR 整体跳过斜杠命令通过author_association校验来限制密钥使用。首次贡献者需经维护者一次手动批准后其后续 PR 才会自动运行 CI。 AI 代码审查BigBonk 与 Bonk每个 PR 都要经过 AI 代码审查。在 CONTRIBUTING.md 中定义了两档智能体BigBonk深度审查由有写权限的贡献者触发擅长发现真实问题与辅助调试Bonk轻量级审查供维护者做快速通过两者都由 OpenCode 驱动、以高推理强度运行。外部贡献者无法直接触发但维护者会代为发起。审查节奏团队会不断迭代 BigBonk 的反馈直到没有未解决的评论。你不必逐字照单全收但维护者认为它非常擅长发现真问题。大型 PR 通常要经过多轮审查。偏合并、不偏阻塞。这是一个有已知缺口的新项目团队的目标是把 PR 合进来。如果你的贡献推动了项目维护者会协助你落地甚至可能直接把建议改动推入你的 PR 并合并同时保留原始作者署名。 对于堆叠式重构 PR在 rebase 或回应评论后用/bigbonk重新触发审查是这里的常规节奏。 从分支到合并标准 Git 工作流AGENTS.md 的Git Workflow章节划出了清晰的边界新手务必遵守永不直接推送 main——main开启了分支保护必需检查项为Check、Vitest、Playwright E2E建分支git checkout -b fix/descriptive-name提交并推送git push -u origin fix/descriptive-name创建 PRgh pr create等待 CI 全绿后合并gh pr merge --squash --delete-branch永不用gh pr merge --admin——它会绕过分支保护合并被阻塞时先排查失败项而非强行通过关于变更日志Changeset不要手动创建。Changeset 会在 CI 中由scripts/create-changeset.mts根据 Conventional Commits自动生成。你只需写规范的提交信息如feat(router): ...、fix(build): ...CI 便会产出对应的变更集。 大型重构请拆成小的堆叠 PR把一段内聚逻辑挪进类型化 helper → 加聚焦测试 → 推送修 CI → 合并后再 rebase 下一个分支审查友好且风险可控。 新手第一步去哪里找任务如果你还不确定该做什么从开放的 issue 入手是最佳起点。同时仓库在examples/下维护了一批真实 Next.js 应用的移植版本如 HN 克隆、Nextra 文档站、Playground它们每次推送到 main 都会部署到 Workers并由 scripts/smoke-test.sh 自动做部署后检查。移植或修复这些示例是上手 vinext 生态的绝佳练兵场。当你遇到 Next.js 应用与 vinext 不兼容的问题README.md 还特别提醒先把 AI 智能体丢给这个问题。让 Claude Code、OpenCode 等工具去追踪 vinext 源码、定位缺口或 bug。一份这是智能体查到的结论的 issue远胜过一句它不工作。总结参与 vinext 开发的钥匙是AI 协作 对齐 Next.js 行为 只守目标测试 走标准 PR 流程。带上你的 AI 工具读懂 AGENTS.md从一个小 issue 开始你就能在这个 AI 驱动的开源项目里顺利贡献并合并你的第一个 PR。【免费下载链接】vinextVite plugin that reimplements the Next.js API surface — deploy anywhere项目地址: https://gitcode.com/gh_mirrors/vi/vinext创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
