EAS CLI 项目架构解析：从模块设计到配置逻辑

一、核心功能模块：理解项目的"器官系统"

1.1 引擎层：Monorepo架构下的多包协同

EAS CLI采用Monorepo架构（像多层抽屉的收纳系统，每个包独立又共享资源），核心功能通过packages/目录下的多个子包实现：

• eas-cli：主命令行工具包，包含所有业务逻辑和命令实现
• eas-json：配置文件解析引擎，处理eas.json的验证与读取
• downloader：资源下载模块，负责安装依赖和工具
• logger：日志系统，统一管理命令行输出
• steps：构建流程控制模块，定义工作流步骤逻辑

💡 工程实践提示：通过lerna.json管理多包版本，执行yarn lerna bootstrap可实现跨包依赖的自动链接

1.2 交互层：命令系统与用户接口

用户通过命令行与系统交互，所有命令定义集中在packages/eas-cli/src/commands/目录，采用分层设计：

• 命令注册：每个命令对应独立文件（如account/login.ts）
• 参数解析：通过flags.ts定义命令行参数规则
• 执行逻辑：核心业务逻辑与API调用分离
• 反馈机制：通过ora.ts提供进度指示，logger输出结果

数据流转路径：用户输入→命令解析→权限验证→业务逻辑→结果输出

💡 工程实践提示：新增命令时需同时更新commands/index.ts和使用文档，保持一致性

1.3 配置层：项目设置的中枢系统

配置系统通过多层级文件实现灵活控制：

• 全局配置：~/.eas/config.json存储用户级设置
• 项目配置：eas.json定义项目构建参数
• 环境变量：.env文件与系统环境变量结合
• 运行时配置：通过命令行参数动态覆盖配置

💡 工程实践提示：使用eas config命令可查看最终生效的合并配置

二、关键文件解析：功能需求的技术实现

2.1 为什么需要单独的ts-declarations目录？

TypeScript声明文件目录ts-declarations/解决了两类问题：

1. 类型补充：为无类型定义的第三方库提供类型声明（如better-opn/index.d.ts）
2. 类型扩展：扩展现有类型定义以满足项目特定需求

存在价值：确保类型安全的同时避免"any"类型滥用，提升代码可维护性

修改场景：引入新的无类型依赖时需添加对应声明文件

2.2 package.json与lerna.json的协作机制

这两个文件构成了项目的包管理核心：

• 版本同步：lerna.json的version字段统一管理所有包版本
• 依赖管理：package.json定义根项目依赖，子包依赖在各自目录管理
• 工作流脚本：根package.json定义跨包脚本，如yarn build触发所有包构建

配置协同关系：

lerna.json  ────── 版本控制 ─────► 所有子包package.json
     │                                 ▲
     │                                 │
     └───── 工作流控制 ────► 根package.json

💡 工程实践提示：版本升级使用yarn lerna version而非直接修改版本号

2.3 .gitignore不仅是排除列表，更是项目边界的定义

.gitignore文件通过精确排除规则定义了项目的边界：

• 构建产物：排除dist/、node_modules/等编译结果
• 环境信息：排除.env、.log等包含敏感信息的文件
• 编辑器配置：排除.idea/、.vscode/等个人配置
• 操作系统文件：排除.DS_Store、Thumbs.db等系统文件

存在价值：保持仓库清洁，避免敏感信息泄露，确保CI/CD环境一致性

三、配置逻辑链：从命令执行到配置加载

3.1 典型开发场景：命令执行的完整路径

以eas build命令为例，文件调用链如下：

1. 入口点：packages/eas-cli/bin/eas（命令行入口）
2. 命令解析：packages/eas-cli/src/commands/build.ts（命令定义）
3. 配置加载：packages/eas-json/src/accessor.ts（读取eas.json）
4. 参数验证：packages/eas-cli/src/commandUtils/flags.ts（参数校验）
5. 业务逻辑：packages/eas-cli/src/builds/（构建核心逻辑）
6. 结果输出：packages/logger/src/index.ts（日志输出）

3.2 新手常见文件混淆对比表

文件	功能定位	协作边界	修改场景
.eslintrc.js	代码质量规则	检测语法错误和代码风格问题	添加新的代码规范或修改规则等级
.prettierrc	代码格式化	仅负责代码格式（缩进、换行等）	调整代码样式偏好
jest.config.ts	测试框架配置	控制测试执行方式	添加测试环境或修改测试覆盖率阈值
tsconfig.json	TypeScript编译配置	控制类型检查和编译输出	调整目标ES版本或模块系统

3.3 文件定位速查表（按功能需求）

功能需求	文件路径
添加新命令	packages/eas-cli/src/commands/
修改构建配置	packages/eas-json/src/schema.ts
调整日志级别	packages/logger/src/level.ts
修改工作流步骤	packages/steps/src/BuildStep.ts
添加API调用	packages/eas-cli/src/graphql/

💡 工程实践提示：使用yarn grep命令快速定位关键词所在文件，如yarn grep "BuildStep"

四、工程化最佳实践

4.1 配置文件修改决策指南

• 频繁修改：.env（环境变量）、eas.json（项目配置）
• 谨慎修改：lerna.json（版本管理）、tsconfig.json（类型配置）
• 极少修改：ts-declarations/（类型声明）、.gitignore（项目边界）

4.2 多包开发工作流

1. 克隆项目：git clone https://gitcode.com/gh_mirrors/ea/eas-cli
2. 安装依赖：yarn install
3. 构建所有包：yarn build
4. 运行测试：yarn test
5. 本地开发：yarn watch（监控文件变化自动编译）
6. 提交代码：yarn commit（使用规范提交信息）

💡 工程实践提示：开发单个包时使用yarn lerna run --scope=<package> dev启动单独开发模式

通过理解EAS CLI的模块设计、文件功能和配置逻辑，开发者可以更高效地参与项目贡献和定制开发，同时把握大型Monorepo项目的工程化最佳实践。