sparrow-ci 1.3.0 → 1.4.0

package/.qoder/repowiki/zh/content//345/221/275/344/273/244/350/241/214/345/217/202/350/200/203//345/221/275/344/273/244/344/275/277/347/224/250/347/244/272/344/276/213.md

@@ -0,0 +1,423 @@
+# 命令使用示例
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [package.json](file://package.json)
+- [ci.config.js](file://ci.config.js)
+- [bin/main.js](file://bin/main.js)
+- [bin/ci.js](file://bin/ci.js)
+- [bin/command/index.js](file://bin/command/index.js)
+- [bin/utils/index.js](file://bin/utils/index.js)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js)
+- [git_tag.sh](file://git_tag.sh)
+- [git.sh](file://git.sh)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与稳定性建议](#性能与稳定性建议)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录：命令速查与最佳实践](#附录命令速查与最佳实践)
+
+## 简介
+本文件面向首次使用与进阶使用者，提供从入门到精通的完整命令使用示例，覆盖首次配置、日常开发工作流、生产发布流程、多环境管理策略等典型场景。每个示例均给出命令序列、预期输出要点与常见问题的定位与解决思路，并总结命令组合的最佳实践（如上传前的预检清单、构建优化、版本管理策略），同时为不同角色（开发者、运维、项目经理）提供关注点与操作建议。
+
+## 项目结构
+该 CLI 工具围绕“命令入口 -> 业务控制器 -> 命令实现 -> 工具函数”的层次化设计组织，核心文件如下：
+- 命令入口：解析命令行参数并调度业务控制器
+- 业务控制器：封装 CI 生命周期（初始化、上传、预览、构建、切换环境、克隆、机器人切换、帮助）
+- 命令实现：对接 miniprogram-ci 完成上传、预览、npm 构建
+- 工具模块：通用 IO、版本处理、进度提示、文件夹复制等
+
+```mermaid
+graph TB
+subgraph "命令层"
+M["bin/main.js<br/>解析参数并调度"]
+end
+subgraph "业务控制层"
+C["bin/ci.js<br/>Ci 类：初始化/上传/预览/构建/切换/克隆/机器人/帮助"]
+end
+subgraph "命令实现层"
+CMD["bin/command/index.js<br/>uploadCi/previewCi/packNpm*"]
+end
+subgraph "工具层"
+U1["bin/utils/index.js<br/>通用工具"]
+U2["bin/utils/node_utils.js<br/>文件/进程/复制"]
+end
+CFG["ci.config.js<br/>全局配置"]
+M --> C
+C --> CMD
+C --> U1
+C --> U2
+C --> CFG
+CMD --> CFG
+```
+
+图表来源
+- [bin/main.js](file://bin/main.js#L1-L63)
+- [bin/ci.js](file://bin/ci.js#L1-L366)
+- [bin/command/index.js](file://bin/command/index.js#L1-L183)
+- [bin/utils/index.js](file://bin/utils/index.js#L1-L222)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L1-L177)
+- [ci.config.js](file://ci.config.js#L1-L48)
+
+章节来源
+- [README.md](file://README.md#L1-L81)
+- [package.json](file://package.json#L1-L23)
+- [bin/main.js](file://bin/main.js#L1-L63)
+- [bin/ci.js](file://bin/ci.js#L1-L366)
+- [bin/command/index.js](file://bin/command/index.js#L1-L183)
+- [bin/utils/index.js](file://bin/utils/index.js#L1-L222)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L1-L177)
+- [ci.config.js](file://ci.config.js#L1-L48)
+
+## 核心组件
+- 命令入口与参数解析：通过 commander 注册选项，解析并分发到 Ci 控制器
+- 业务控制器 Ci：负责初始化、读写 cli.js、环境切换、上传/预览/构建/克隆/机器人切换/帮助
+- 命令实现：封装 miniprogram-ci 的上传、预览、npm 构建逻辑，带进度反馈
+- 工具模块：版本格式化、文件读写、依赖安装、文件夹复制、执行外部脚本等
+
+章节来源
+- [bin/main.js](file://bin/main.js#L14-L62)
+- [bin/ci.js](file://bin/ci.js#L21-L366)
+- [bin/command/index.js](file://bin/command/index.js#L17-L182)
+- [bin/utils/index.js](file://bin/utils/index.js#L36-L222)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L24-L177)
+
+## 架构总览
+下面的序列图展示了“上传”命令从入口到上传完成的关键调用链路。
+
+```mermaid
+sequenceDiagram
+participant User as "用户"
+participant Main as "bin/main.js"
+participant CI as "bin/ci.js"
+participant CMD as "bin/command/index.js"
+participant MP as "miniprogram-ci"
+User->>Main : "ci --upload"
+Main->>CI : "new Ci().init()"
+CI->>CI : "检查/创建 cli.js<br/>读取/写入配置"
+Main->>CI : "ci.upload()"
+CI->>CMD : "uploadCi(params)"
+CMD->>MP : "ci.upload(...)"
+MP-->>CMD : "进度回调/结果"
+CMD-->>CI : "完成"
+CI-->>User : "打印上传结果/二维码链接"
+```
+
+图表来源
+- [bin/main.js](file://bin/main.js#L27-L62)
+- [bin/ci.js](file://bin/ci.js#L267-L301)
+- [bin/command/index.js](file://bin/command/index.js#L29-L69)
+
+章节来源
+- [bin/main.js](file://bin/main.js#L27-L62)
+- [bin/ci.js](file://bin/ci.js#L267-L301)
+- [bin/command/index.js](file://bin/command/index.js#L29-L69)
+
+## 详细组件分析
+
+### 组件一：命令入口与参数分发
+- 功能要点
+  - 注册选项：上传、预览、切换环境、npm 构建、克隆、机器人、帮助
+  - 初始化 Ci 实例并等待初始化完成
+  - 根据参数分支调用对应方法
+- 关键行为
+  - 默认输出帮助
+  - 支持组合参数（例如在线发布代码开关）
+
+章节来源
+- [bin/main.js](file://bin/main.js#L14-L62)
+
+### 组件二：业务控制器 Ci（初始化与配置）
+- 初始化流程
+  - 读取项目配置，解析 appid、miniprogramRoot、app.json、分包信息
+  - 检查并创建独立分包目录
+  - 检查/创建 cli.js 并写入默认配置
+  - 安装依赖并执行 npm 构建
+- 配置读写
+  - 读取/写入 cli.js，支持环境、版本、描述、项目根路径、机器人编号
+  - 在线发布时从 git tag 读取版本与描述
+- 交互式问答
+  - 通过 inquirer 弹窗收集环境、版本、描述等必要信息
+
+```mermaid
+flowchart TD
+Start(["初始化入口"]) --> ReadCfg["读取 project.config.json/app.json"]
+ReadCfg --> CheckCli{"cli.js 是否存在？"}
+CheckCli --> |否| CreateCli["创建 cli.js 并写入默认配置"]
+CreateCli --> InstallDeps["安装依赖"]
+InstallDeps --> BuildNpm["执行 npm 构建"]
+BuildNpm --> DoneInit["初始化完成"]
+CheckCli --> |是| CopyToSub["复制 cli.js 到独立分包"]
+CopyToSub --> ReadCli["读取 cli.js 并同步到实例"]
+ReadCli --> DoneInit
+```
+
+图表来源
+- [bin/ci.js](file://bin/ci.js#L56-L86)
+- [bin/ci.js](file://bin/ci.js#L117-L139)
+- [bin/ci.js](file://bin/ci.js#L142-L146)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L74-L100)
+- [bin/ci.js](file://bin/ci.js#L304-L313)
+
+章节来源
+- [bin/ci.js](file://bin/ci.js#L56-L86)
+- [bin/ci.js](file://bin/ci.js#L117-L146)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L24-L100)
+
+### 组件三：上传命令（uploadCi）
+- 行为特征
+  - 读取版本、描述、机器人编号
+  - 调用 miniprogram-ci 上传，启用压缩、条件编译等设置
+  - 进度回调：进行中/完成状态提示
+  - 成功后打印各分包大小统计
+- 错误处理
+  - 失败时输出错误信息并标记失败
+
+```mermaid
+sequenceDiagram
+participant CI as "bin/ci.js"
+participant CMD as "bin/command/index.js"
+participant MP as "miniprogram-ci"
+CI->>CMD : "uploadCi(params)"
+CMD->>MP : "ci.upload(setting, robot)"
+MP-->>CMD : "onProgressUpdate(status)"
+CMD-->>CI : "返回 subPackageInfo"
+CI-->>CI : "打印分包大小统计"
+```
+
+图表来源
+- [bin/ci.js](file://bin/ci.js#L267-L301)
+- [bin/command/index.js](file://bin/command/index.js#L29-L69)
+
+章节来源
+- [bin/ci.js](file://bin/ci.js#L267-L301)
+- [bin/command/index.js](file://bin/command/index.js#L29-L69)
+
+### 组件四：预览命令（previewCi）
+- 行为特征
+  - 生成体验版二维码图片，支持指定页面、查询参数、场景值
+  - 进度回调提示生成中/完成
+- 注意事项
+  - 命令行中 & 需要转义为 \&
+
+章节来源
+- [bin/ci.js](file://bin/ci.js#L315-L325)
+- [bin/command/index.js](file://bin/command/index.js#L135-L175)
+
+### 组件五：npm 构建（packNpmCi / packNpmListCi）
+- 行为特征
+  - 单项目：根据 package.json 与 miniprogramRoot 手动打包
+  - 多项目：按配置中的 packNpmRelationList 并行打包
+  - 输出构建数量与告警列表
+- 适用场景
+  - 依赖较多或多子项目时提升效率
+
+章节来源
+- [bin/ci.js](file://bin/ci.js#L304-L313)
+- [bin/command/index.js](file://bin/command/index.js#L72-L133)
+
+### 组件六：环境切换与机器人切换
+- 环境切换
+  - 交互式选择 DEV/PRO，写回 cli.js 并提示成功
+- 机器人切换
+  - 支持按名称映射到机器人编号，写回 cli.js 并提示成功
+
+章节来源
+- [bin/ci.js](file://bin/ci.js#L332-L347)
+- [bin/ci.js](file://bin/ci.js#L349-L356)
+- [ci.config.js](file://ci.config.js#L15-L22)
+
+### 组件七：克隆文件夹（独立分包复制）
+- 行为特征
+  - 将源目录集合复制到每个独立分包的目标位置
+- 适用场景
+  - 统一资源/工具库在多分包间复用
+
+章节来源
+- [bin/ci.js](file://bin/ci.js#L327-L330)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L117-L168)
+- [ci.config.js](file://ci.config.js#L28-L29)
+
+### 组件八：帮助与全局配置
+- 帮助
+  - 输出帮助描述，包含各命令简写与作用
+- 全局配置
+  - 环境枚举、机器人映射、直播插件地址/列表、源目录集合、帮助描述
+
+章节来源
+- [bin/ci.js](file://bin/ci.js#L358-L362)
+- [ci.config.js](file://ci.config.js#L10-L47)
+
+## 依赖关系分析
+- 外部依赖
+  - miniprogram-ci：小程序上传/预览/构建的核心能力
+  - commander/inquirer/ora/chalk/log-symbols：命令行参数解析、交互、进度与颜色输出
+- 内部依赖
+  - bin/main.js 依赖 bin/ci.js
+  - bin/ci.js 依赖 bin/command/index.js 与 bin/utils/*
+  - bin/command/index.js 依赖 ci.config.js 与工具函数
+
+```mermaid
+graph LR
+P["package.json<br/>bin 映射"] --> MAIN["bin/main.js"]
+MAIN --> CI["bin/ci.js"]
+CI --> CMD["bin/command/index.js"]
+CI --> U["bin/utils/*.js"]
+CMD --> CFG["ci.config.js"]
+CI --> CFG
+```
+
+图表来源
+- [package.json](file://package.json#L6-L8)
+- [bin/main.js](file://bin/main.js#L11-L12)
+- [bin/ci.js](file://bin/ci.js#L14-L17)
+- [bin/command/index.js](file://bin/command/index.js#L10-L15)
+- [ci.config.js](file://ci.config.js#L1-L48)
+
+章节来源
+- [package.json](file://package.json#L1-L23)
+- [bin/main.js](file://bin/main.js#L11-L12)
+- [bin/ci.js](file://bin/ci.js#L14-L17)
+- [bin/command/index.js](file://bin/command/index.js#L10-L15)
+- [ci.config.js](file://ci.config.js#L1-L48)
+
+## 性能与稳定性建议
+- 构建优化
+  - 使用多项目并行打包（packNpmListCi）减少等待时间
+  - 合理配置 packNpmRelationList，避免重复构建
+- 上传稳定性
+  - 保持微信开发者工具服务端口开启
+  - 确保私钥路径正确，避免上传失败
+- 版本管理
+  - 使用 git tag 作为版本来源，结合在线发布流程自动化
+- 日志与可观测性
+  - 上传/预览均带有进度回调，便于监控耗时与异常
+
+[本节为通用建议，不直接分析具体文件]
+
+## 故障排查指南
+- 无法找到命令
+  - 若仅在项目内安装，请使用 npx 前缀调用
+- 上传失败
+  - 检查微信开发者工具服务端口是否开启
+  - 确认私钥路径与机器人编号
+  - 查看进度回调中的错误信息
+- npm 构建无效果
+  - 确认版本号为三位格式（工具会做格式化处理）
+  - 检查 packNpmRelationList 是否正确配置
+- 依赖安装失败
+  - 确认 package.json 存在且网络正常
+- 预览参数无效
+  - 注意命令行中 & 需要转义为 \&
+- 在线发布版本/描述不正确
+  - 确认 git tag 输出格式符合预期，工具会解析首条 tag 的版本与描述
+
+章节来源
+- [README.md](file://README.md#L16-L34)
+- [bin/command/index.js](file://bin/command/index.js#L29-L69)
+- [bin/command/index.js](file://bin/command/index.js#L135-L175)
+- [bin/utils/index.js](file://bin/utils/index.js#L28-L34)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L74-L100)
+- [bin/ci.js](file://bin/ci.js#L240-L263)
+
+## 结论
+本 CLI 工具通过清晰的分层设计与完善的命令集，覆盖了小程序 CI 的上传、预览、构建、环境与机器人管理等关键环节。配合版本与多项目构建策略，可在团队协作中显著提升效率与一致性。建议在团队内统一使用本指南中的示例流程与最佳实践，确保跨角色协作顺畅。
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录：命令速查与最佳实践
+
+### 角色关注点
+- 开发者
+  - 日常上传、预览、npm 构建、环境切换、机器人切换
+- 运维
+  - 依赖安装、私钥路径、上传/预览权限、日志与进度监控
+- 项目经理
+  - 版本与描述规范、在线发布流程、多环境策略
+
+### 示例场景与命令序列
+
+- 首次使用配置
+  - 步骤
+    - 初始化：执行命令触发初始化（创建 cli.js、安装依赖、构建 npm）
+    - 验证：确认 cli.js 内容与项目根路径、环境、版本、描述、机器人编号
+  - 参考命令
+    - ci --upload（首次会触发初始化）
+    - ci --build-npm
+  - 预期输出
+    - 初始化完成后提示“初始化完成”
+    - 构建成功后输出构建数量与告警列表
+  - 常见问题
+    - 未安装依赖导致构建失败：先执行依赖安装流程
+    - 私钥路径错误导致上传失败：检查私钥所在目录
+
+- 日常开发工作流
+  - 步骤
+    - 切换环境：选择 DEV/PRO
+    - 修改版本与描述：交互式输入
+    - 上传：执行上传命令
+    - 预览：生成体验版二维码
+  - 参考命令
+    - ci --switch
+    - ci --upload
+    - ci --preview
+  - 预期输出
+    - 环境切换成功提示
+    - 上传完成后提示可在管理后台选择体验版
+    - 预览完成后生成二维码图片
+
+- 生产环境发布流程
+  - 步骤
+    - 从 git tag 读取版本与描述
+    - 使用在线发布开关自动切换机器人并上传
+    - 上传完成后在管理后台选择体验版
+  - 参考命令
+    - ci --online-publish-code
+    - git_tag.sh（辅助读取最新 tag）
+  - 预期输出
+    - 在线发布流程自动写入版本与描述
+    - 上传成功后输出分包大小统计
+
+- 多环境管理策略
+  - 步骤
+    - 通过 --switch 在 DEV/PRO 之间切换
+    - 通过 --robot 指定不同机器人编号
+  - 参考命令
+    - ci --switch
+    - ci --robot 名称
+  - 预期输出
+    - 环境切换成功提示
+    - 机器人切换成功提示
+
+- 命令组合最佳实践
+  - 上传前预检清单
+    - 确认微信开发者工具服务端口开启
+    - 确认私钥路径与机器人编号
+    - 确认版本号为三位格式
+  - 构建优化技巧
+    - 使用多项目并行打包
+    - 合理配置 packNpmRelationList
+  - 版本管理策略
+    - 使用 git tag 作为版本来源，结合在线发布流程
+    - 预览参数中的 & 需要转义为 \&
+
+章节来源
+- [README.md](file://README.md#L16-L34)
+- [bin/main.js](file://bin/main.js#L14-L23)
+- [bin/ci.js](file://bin/ci.js#L332-L356)
+- [bin/ci.js](file://bin/ci.js#L240-L263)
+- [bin/command/index.js](file://bin/command/index.js#L29-L69)
+- [bin/command/index.js](file://bin/command/index.js#L135-L175)
+- [bin/utils/index.js](file://bin/utils/index.js#L28-L34)
+- [bin/utils/node_utils.js](file://bin/utils/node_utils.js#L74-L100)
+- [ci.config.js](file://ci.config.js#L15-L22)
+- [git_tag.sh](file://git_tag.sh#L1-L10)