日常工作知识库

Appearance

CBM CLI start 与一键脚本快速上手 ​

归类：cli / 工程化接入 / 开发启动 发生时间：2026-03-30 状态：✅ 已形成稳定工作流

一、适用场景 ​

当一个通用业务项目需要快速接入 CBM，目标通常不是只生成配置文件，而是一次性完成下面几件事：

  1. 检查当前机器和项目的基础环境。
  2. 补齐业务依赖与 CBM 运行时依赖。
  3. 初始化 cbm.config.js 和按需注册表。
  4. 自动注入入口代码。
  5. 同时拉起业务开发服务与 CBM Worker。
  6. 在后台保障 MCP 服务可用，但不阻塞业务主链路。

cbm start 就是围绕这条链路设计的默认入口。

二、两种推荐入口 ​

1. 已经装过 CLI：直接执行 cbm start ​

bash
cbm start --yes --port 5885

这适合已经具备 CLI 环境的日常开发场景。

2. 首次使用：先走团队提供的一键 bootstrap 脚本 ​

bash
curl -fsSL <team-bootstrap-script> | bash

推荐把这条脚本作为“第一次接触 CBM”的默认入口。它的职责应该是：

  1. 识别当前机器是否已经具备可用的 Node 与包管理环境。
  2. 自动安装或升级 cbm-cli。
  3. 修复高风险的 npm prefix / cache / registry 配置冲突。
  4. 如果当前目录就是业务项目，则自动继续执行 cbm start。

这样用户不用先理解 CLI 安装、私有源、Node 切换和依赖补齐细节。

三、cbm start 默认会做什么 ​

当前推荐把 cbm start 理解成“一键接入并启动”的编排命令，而不是单纯的初始化脚本。典型流程如下：

  1. 检查环境并准备项目级包管理缓存。
  2. 同步项目级 registry 配置，避免公共包和私有包来源混乱。
  3. 自动补齐业务依赖与 @cbm/cbm-render 等运行时依赖。
  4. 默认生成 window 按需模式的注册表。
  5. 初始化或补齐 cbm.config.js。
  6. 生成 registerCBMComponents.ts 并注入项目入口。
  7. 启动 watch:worker。
  8. 启动业务项目自己的 serve / dev / start 脚本。
  9. 以后台保障模式检查并拉起 MCP 服务。

这意味着它既覆盖“接入”，也覆盖“启动”。

四、Node 版本建议 ​

对于老的 Vue 2 / Vue CLI 4 业务项目，最佳实践不是一刀切升级到最新 Node，而是优先使用项目兼容的版本。

推荐原则：

  1. 如果项目本身固定在 Node 14 或 Node 16，优先复用项目兼容版本。
  2. 如果当前终端版本过高，但项目明显属于 Vue 2 / Vue CLI 4，启动前应优先切到兼容版本再执行。
  3. 首次一键 bootstrap 脚本应能自动完成这一步，而不是把 Node 切换责任完全留给用户。

五、成功启动后应该看到什么 ​

一次成功的启动，通常会出现下面几类结果：

  1. 业务 dev server 端口已经监听。
  2. CBM Worker WebSocket 端口已经监听。
  3. 项目里生成了 cbm.config.js、按需注册表和入口注入代码。
  4. MCP 状态检查显示“配置存在 / 服务已安装 / 配置有效 / 服务运行中”。

如果业务模板本身存在 ESLint、Prettier 或 Sass warning，只要 dev server 仍然成功起来，这类 warning 一般不应视为 cbm start 失败。

六、常见排查思路 ​

1. 安装阶段卡住或报权限错误 ​

优先检查：

  1. 是否用了用户可写的全局安装目录。
  2. npm cache 是否落在项目级或用户级目录，而不是历史残留的 root-owned 目录。
  3. registry 是否统一到了团队要求的私有源。

2. node_modules 存在但业务仍然起不来 ​

这类问题常见原因是：

  1. 启动脚本依赖对应的 .bin 实际缺失。
  2. 运行时依赖存在版本漂移。

更稳妥的做法，是让 cbm start 不只检查 node_modules 是否存在，还要检查真正启动所需的关键依赖是否就绪。

3. MCP 相关问题影响主链路 ​

推荐做法是把 MCP 放在后台保障模式里：

  1. 已可用就直接复用。
  2. 未安装则异步安装和拉起。
  3. 即使 MCP 启动失败，也不要阻塞业务服务和 Worker。

七、推荐给团队的默认习惯 ​

  1. 第一次进入项目时，优先运行团队维护的一键 bootstrap 脚本。
  2. 后续日常开发时，直接运行 cbm start --yes --port <worker-port>。
  3. 遇到问题时，优先检查 Node 版本、registry、缓存目录和 cbm mcp --check 结果。

八、结论 ​

把 cbm start 作为默认入口、把 bootstrap 脚本作为首次接入入口，能显著降低业务同学第一次接入 CBM 的理解成本。

真正稳定的体验，不是只让命令“能跑”，而是把下面这些前置问题一起自动化处理：

  1. Node 版本选择。
  2. 私有源与依赖安装策略。
  3. 项目级缓存与权限冲突。
  4. 注册表生成与入口注入。
  5. 业务服务、Worker 和 MCP 的联动启动。