DevEco Code 构建与安装教程¶

本教程介绍如何将 DevEco Code 源码构建成可独立运行的单文件二进制，并像 npm install -g 一样直接安装到系统中使用。

一、前置要求¶

二、构建原理¶

DevEco Code 的二进制由 packages/opencode/script/build.ts 生成。核心机制：

1. 使用 Bun.build 的 compile 选项，将整个应用编译成单文件可执行二进制，无需 Node 运行时即可运行。
2. 编译时把以下资源一并内嵌进二进制：
3. 前端 Web UI（gen-web-ui.ts 先构建 SolidJS 应用，再作为 deveco-web-ui.gen.ts 嵌入）
4. 数据库迁移脚本（migration/ 目录）
5. 默认 Skills（resources/skills/）
6. 默认 Spec 资源（resources/spec/）
7. tree-sitter 解析 worker、TUI worker
8. 构建时会额外复制 vendored 二进制到产物目录：
9. ripgrep（由 script/postinstall.ts 在 bun install 时下载到 .build-cache/）
10. ui-verification-mcp（UI 检查运行时）
11. @deveco/deveco-cli（仅 macOS / Windows，用于 curl/irm zip 安装）
12. 每个目标平台输出到独立目录，并生成对应的 package.json（含 os / cpu / libc 字段），供 npm 发布与安装使用。

产物目录结构：

packages/opencode/dist/deveco-<os>-<arch>/
├── bin/
│   └── deveco          # 单文件可执行二进制
├── vendor/
│   ├── ripgrep/        # vendored rg 二进制
│   └── ui-verification-mcp/
├── CHANGELOG.md
├── LICENSE
├── README.md
└── package.json

注意目录名与包名不同：构建产物目录名由 packages/opencode/package.json 的 name 字段（deveco）+ 平台后缀组成（如 deveco-linux-x64）；而该目录内 package.json 的 npm 包名才是 @deveco/deveco-code-linux-x64（见下文的发布机制）。

三、构建步骤¶

1. 安装依赖¶

cd /path/to/deveco-code
bun install

注意：bun install 的 postinstall 钩子会下载 ripgrep 等 vendored 二进制到 .build-cache/。若网络受限，可设置 HTTPS_PROXY / HTTP_PROXY 代理，或通过 RIPGREP_DOWNLOAD_BASE 指定镜像源。

2. 构建当前平台的二进制¶

./packages/opencode/script/build.ts --single

--single 只构建当前平台、当前架构的原生版本（跳过 musl / baseline 变体），速度快，适合本地使用。

构建完成后，产物位于：

packages/opencode/dist/deveco-linux-x64/bin/deveco   # Linux x64 示例

脚本会自动对当前平台的产物执行 --version 冒烟测试：

Running smoke test: dist/deveco-linux-x64/bin/deveco --version
Smoke test passed: <版本号>

3.（可选）构建全部平台¶

./packages/opencode/script/build.ts

不带 --single 会构建 allTargets 中定义的 10 个目标（darwin-arm64 / darwin-x64 / win32-x64 / win32-x64-baseline / linux-arm64 / linux-x64 / linux-x64-baseline / linux-arm64-musl / linux-x64-musl / linux-x64-musl-baseline），耗时较长，一般只在发布时使用。

4. 常用构建参数¶

四、安装二进制（像 npm install 一样）¶

构建出的二进制是自包含的，不需要 Node 运行时即可运行。以下三种方式任选其一。

方式一：软链接到 PATH（推荐，最简单）¶

sudo ln -s \
  /path/to/deveco-code/packages/opencode/dist/deveco-linux-x64/bin/deveco \
  /usr/local/bin/deveco

deveco --version    # 验证
deveco              # 启动

方式二：复制到系统目录¶

sudo cp /path/to/deveco-code/packages/opencode/dist/deveco-linux-x64/bin/deveco /usr/local/bin/
sudo chmod +x /usr/local/bin/deveco

方式三：本地打包为 npm 包安装（仅装二进制，不生成命令）¶

模拟官方发布流程，在产物目录执行：

cd packages/opencode/dist/deveco-linux-x64
bun pm pack
npm install -g deveco-deveco-code-linux-x64-*.tgz

注意（易踩坑）：该 tgz 是平台包（@deveco/deveco-code-linux-x64），其 package.json 没有 bin 字段，npm install -g 不会自动创建 deveco 命令。官方 npm 安装中的 deveco 命令由元包 @deveco/deveco-code 提供（含 bin 启动器 + postinstall 脚本 + optionalDependencies），但官方元包只覆盖 macOS / Windows（ALLOWED_PLATFORMS 不含 Linux），Linux 上无法通过官方元包安装。

平台包安装后，需手动把已安装的二进制链接到 PATH：

# 查看全局安装路径
npm root -g    # 例如 .../installation/lib/node_modules

# 全局可执行目录为 prefix 下的 bin，而非 `npm bin -g`（该子命令在较新 npm 版本已移除）
ln -sf "$(npm root -g)/@deveco/deveco-code-linux-x64/bin/deveco" "$(npm config get prefix)/bin/deveco"

若本地已有构建产物 packages/opencode/dist/deveco-linux-x64/bin/deveco，直接链接构建产物更简单（即方式一）。

卸载¶

# 软链接 / 复制方式
sudo rm /usr/local/bin/deveco

# npm 方式
npm uninstall -g <包名>

五、官方 npm 分发机制¶

线上 npm install -g @deveco/deveco-code 的工作原理（见 packages/opencode/script/publish.ts）：

1. build.ts 为每个平台生成 @deveco/deveco-code-<os>-<arch> 平台包（含二进制，preferUnplugged: true）。
2. 生成元包 @deveco/deveco-code：
3. bin.deveco 指向 ./bin/deveco（一个 Node 启动器，负责 spawn 对应平台的二进制）
4. optionalDependencies 列出所有平台包（npm 会自动只安装当前平台匹配的那个）
5. postinstall 执行 postinstall.mjs（安装后处理）
6. 发布时 publish.ts 会：
7. 过滤平台（ALLOWED_PLATFORMS：darwin-arm64 / darwin-x64 / win32-x64）
8. 对每个平台包执行 bun pm pack + npm publish
9. 最后发布元包

npm install -g @deveco/deveco-code
        │
        ▼
元包（@deveco/deveco-code）
  ├── optionalDependencies  → 自动安装匹配当前平台的包
  │     └── @deveco/deveco-code-linux-x64
  │           └── bin/deveco  ← 真正的单文件二进制
  ├── bin/deveco             ← Node 启动器，spawn 平台二进制
  └── postinstall.mjs        ← 安装后处理

六、常见问题与注意事项¶

1. Linux 支持情况¶

• 源码支持构建 Linux 二进制（linux-arm64 / linux-x64 / musl 变体）。
• 官方 npm 包暂不支持 Linux：publish.ts 的 ALLOWED_PLATFORMS 仅包含 darwin-arm64、darwin-x64、win32-x64。若需在 Linux 使用，请按本教程自行构建（方式一 / 方式二）。
• HarmonyOS 编译构建、模拟器与真机调试依赖 DevEco Studio（仅 Windows / macOS 可用），Linux 上这些能力不可用。

2. 构建失败：ripgrep 缓存找不到¶

ERROR: ripgrep cache not found for <platform>. Run "bun install" first to download vendored binaries.

说明 .build-cache/ripgrep/ 下没有对应平台的 rg 二进制。先执行：

bun install

或手动执行 bun run packages/opencode/script/postinstall.ts。

3. 修改了 API / SDK 后需重新生成¶

改动 packages/opencode/src/server/server.ts 等 API 相关代码后，构建前先运行：

./script/generate.ts                      # 重新生成 SDK / 客户端代码
./packages/sdk/js/script/build.ts         # 重新构建 JS SDK

4. 更新依赖¶

bun update
bun install

5. 发布流程（维护者）¶

正式发布走 script/publish.ts：

bun run script/publish.ts

它会更新所有包的版本号、重新构建 SDK、构建全部平台二进制并发布到 npm，最后打 tag 推送到远端。