Expo 仓库的 Agent 开发工作流：et CLI、红绿测试与提交规范的完整实践

Expo 仓库的 Agent 开发工作流et CLI、红绿测试与提交规范的完整实践【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo本文基于 Expo 仓库中的 Agent 指令文档 .claude/CLAUDE.md 展开完整还原在该 monorepo 中贡献代码的标准工作流仓库自带 CLIexpotoolset的调用方式与底层实现、红绿red/green测试规则、Jest 与 Swift/Kotlin 原生单测的编写位置与运行命令、基于 Turborepo 的提交前校验流程以及 PR 提交与错误信息撰写的团队规范。读完本文你可以直接在 Expo 仓库中独立完成从开发、测试、校验到提交 PR 的完整闭环。expotoolset仓库专属 CLI 的调用方式Expo 仓库自带一个内部 CLI 工具expotools直接以et command ...args形式调用。文档中特别强调必须直接调用et不要通过npx、bunx或pnpm run间接执行该命令由.envrc中的PATH_add bin通过direnv注入 PATH。如果 shell 中找不到et只需在仓库根目录执行一次direnv allow兜底方式是绕过 PATH 直接用 Node 执行node ./tools/bin/expotools.js command。仓库中大量流程原生单测、prebuild 等都依赖它因此掌握et是贡献 Expo 的第一步。源码印证et的自动重建机制从源码结构看et之所以可以在空依赖环境下直接运行是因为 tools/bin/expotools.js 是一个自举包装器它在 tools/package.json 中注册为bin字段下的et与expotools两个入口main: build/expotools.js并在启动时计算src/源码校验和calculateSourceChecksumAsync若cache/.state.json中记录的校验和与当前不一致或build/目录不存在就自动重新编译 TypeScript 后再加载命令——这就是注释里 “Rebuilding expotools” 提示的来源。CLI 参数解析则基于expo/commander见 tools/package.json 的依赖声明。et check-packages最常用的一条命令check-packages用于验证目标包可以成功构建且测试通过是开发过程中最常触达的命令。其完整参数定义见 tools/src/commands/CheckPackages.ts# 校验指定包别名et check / et cp et check-packages ...packages # 常用选项 et check-packages --since commit # 增量校验只检查自该提交以来受影响的包默认基准为 main 分支 HEAD et check-packages --all # 检查全部包忽略 --since et check-packages --core # 额外强制检查核心包expo、expo-modules-core et check-packages --no-test # 跳过 test 任务 et check-packages --no-lint # 跳过 lint 任务 et check-packages --fix-lint # 以 --fix 模式运行 lint单独成批执行 et check-packages --no-format # 跳过 format 任务 et check-packages --fix-format # format 任务带 --write 自动修正 et check-packages --no-dependency-check # 跳过 depscheck 任务任务组装逻辑同样值得注意CheckPackages.tsbuild与typecheck恒定执行——因为build会重新生成产物depscheck、test、lint默认开启可分别用--no-*关闭核心包常量CORE_PACKAGES [expo, expo-modules-core]--core会将其无条件加入检查范围。底层实现et如何驱动 Turborepotools/src/Turbo.ts 中的runTurboTasksAsync是共享的任务执行入口它把参数翻译成pnpm turbo run tasks...filters→ 逐个转成--filterpkgaffected→ 追加--affected并通过环境变量TURBO_SCM_BASE传入--since基准 refcontinueOnError→ 追加--continuedependencies-successful即某个包失败时仍继续运行其依赖已成功的包保证一次运行能看到尽可能多的失败项passthroughArgs→ 追加在--之后透传给底层 npm script例如lint --fix。这与 turbo.json 中的任务定义一一对应build声明build/**、plugin/build/**、cli/build/**、utils/build/**为产物并依赖^build、typecheck、depscheck、lintcache: false、format依赖lint、testcache: falseoutputLogs: errors-only。此外还配置了concurrency: 90%、10 天/10GB 的本地缓存上限以及远程缓存本地校验与 CI 走的是同一套任务图Turbo.ts中注释明确说明该函数同时被check-packages和发布流水线共用。红绿规则Red/Green先有失败测试再写实现文档将测试驱动作为硬性规则Red/green:先写测试并让它失败然后再实现功能或修复问题直到测试通过。不允许在失败测试存在之前就编写实现。这条规则约束的是开发顺序而非仅测试覆盖先看到红色的失败输出确认断言确实覆盖了目标行为再进入绿色的实现阶段。编写测试JS/TS 单元测试单元测试使用Jest文件紧邻源码存放两种约定位置独立目录__tests__/或与源码同级的*.test.ts文件例如 tools/src/commands 相关的测试 中即可见到*.test.ts命名惯例。这些测试会作为et check-packages流程中test任务的一部分运行因此“提交前跑一次et check-packages”即等价于“构建 类型检查 单测”的完整验证。Swift/Kotlin 原生测试原生单元测试的组织与运行方式存放位置Swift/Kotlin 单测位于packages/pkg/ios/Tests/与packages/pkg/android/目录下运行命令统一通过et native-unit-tests执行可按包缩小范围# 运行所有提供原生测试的包 et native-unit-tests # 只测 iOS 平台、只测 expo/ui 包 et native-unit-tests -p ios --packages expo/ui命令的完整选项定义见 tools/src/commands/NativeUnitTests.ts-p, --platform stringandroid、ios或both不传时命令会用交互式提问inquirer让你选择默认android-t, --type stringlocal默认或instrumented如平台支持--packages string逗号分隔的包名列表缺省为所有提供单测的包--affected只测自--since默认main以来受变更影响的包及其依赖方目前仅 iOS 支持且传了--packages时会被忽略。实现上该命令分别委托给 AndroidNativeUnitTests.ts 与 IosNativeUnitTests.ts。iOS/macOS 的 pod install 注意事项文档给出一条容易踩坑的实操建议在iOS/macOS 上运行原生测试或构建之前必须先安装 Pods每当新增或修改 iOS 的test_spec后需要再次pod installAndroid 无此步骤直接运行pod install不要用et pod-install——直接运行更快且避免为你没在工作的应用例如 Expo Go也安装依赖iOS 单测是针对 bare-expo 应用运行的因此 Pods 应安装在apps/bare-expo/ios目录下执行。提交前校验Turborepo 与et check-packages的关系提交commit之前文档允许用两种方式跑全量任务# 方式一Turborepo 直接跑某任务到所有依赖方 turbo run task # 例如 build、typecheck、depscheck、test、lint # 方式二只针对改动过的包与 CI 的校验方式一致 et check-packages ...改动的包名两条路径最终殊途同归et check-packages内部就是runTurboTasksAsync调用pnpm turbo run见 tools/src/Turbo.ts因此本地结果与 CI 检查具有可比性。关于产物提交有一条明确的红线编译产物build/已被 gitignore.gitignore 第 22 行的/packages/**/build/规则不纳入版本控制Turborepo 会按需重新生成并缓存build/对应 turbo.json 中build任务的outputs声明只暂存源码改动绝不把build/加进提交。创建 PR提交信息与描述规范PR 流程以 CONTRIBUTING.md 贡献指南与仓库 PR 模板.github/PULL_REQUEST_TEMPLATE为准核心要求如下。提交信息commit message格式固定为[平台][api] 标题例如[ios][video] Fix black screen on older devicesPR 描述各部分Why改动动机关联相关 issue、论坛帖子或功能请求How功能如何实现、bug 如何修复以及为什么选择该方案Test Plan说明如何测试、评审者如何复现——当没有自动化测试时附上终端输出或截图Checklist已添加CHANGELOG.md条目已通过et check-packages验证构建、类型检查、lint 与测试参考 guides/contributing/Updating Changelogs.md 了解 changelog 更新规范如相关确认改动可配合npx expo prebuild与 EAS Build 工作符合文档写作风格指南见 guides/Expo Documentation Writing Style Guide.md。提交前最后检查运行et check-packages覆盖构建、类型检查、lint 与测试清理多余的console.log与被注释掉的代码确认没有把 gitignore 的build/产物暂存进去。错误信息撰写规范What / Why / How文档对面向用户的错误信息提出了结构化的写法要求这也是阅读 Expo CLI 源码时会反复遇到的一种风格What明确说明失败了什么Why在用户的抽象层级上解释可能原因而不是复述症状How告诉用户下一步做什么——修复方法、变通方案、调试步骤或何时联系支持。用户通常是开发者。语气要求具体、冷静、可执行specific, calm, and actionable不能止步于症状即使确切修法未知也必须给出一个有用的下一步。诊断细节只在有助于排障时提供并清晰标注。文档给出的完整示例The JavaScript bundler couldnt bundle your code because it depends on a Node.js native addon (node_modules/example/example.node). Use a different package fully implemented in JavaScript, or see the Metro resolution docs if this package already provides one and the bundler may not be configured to resolve it.这条错误信息同时回答了 What打包器无法打包、Why依赖了 Node.js 原生 addon、How换纯 JS 包或检查解析配置。小结.claude/CLAUDE.md 用一页篇幅把 Expo 仓库的日常开发纪律浓缩成了可执行清单direnv allow启用et、et check-packages对齐 CI 校验、红绿规则约束开发顺序、et native-unit-tests加apps/bare-expo/ios下的pod install覆盖原生测试、build/永不入 git、PR 按 Why/How/Test Plan/Checklist 四段填写。结合 tools/ 下的命令源码CheckPackages.ts、NativeUnitTests.ts、Turbo.ts与 turbo.json 的任务定义可以确认这些规范并非口号而是由仓库内工具链直接支撑和执行的工程约定。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考