在 Cursor / VS Code 侧栏提供可视化工具栏，调用本机已安装的 DevEco Studio 工具链（ohpm / hvigorw / hdc），完成鸿蒙工程的依赖安装、编译、多模块部署与真机装机。
本扩展不会内嵌 DevEco IDE，也不替代 Preview / 断点调试。适合「用 Cursor 写代码 + 用同一套 CLI 编译装机」的日常流程。
功能概览
- 侧栏 DevEco 工具栏：一键 Sync / Clean / 构建 / 装机 / 启动
- debug / release 切换（写入工作区配置）
- Multi Deploy：对齐 DevEco「Deploy Multi HAP/HSP」——按模块
assembleHap + assembleHsp 后装机并启动
- 增量构建并安装：优先对比「上次成功装机」的整仓
write-tree；无快照时回退到 git 相对 HEAD；HAR 变更会展开到依赖它的 HAP/HSP
- 模块列表仅展示可安装类型：
entry / feature / shared（排除 HAR）
- 必选模块（默认
entry）在配置列表中锁定，不可取消
- 一键初始化：探测 DevEco、写入配置、同步装机脚本、检查工具链
- 状态栏快捷入口与常用快捷键
环境要求
| 项 |
说明 |
| 编辑器 |
Cursor 或 VS Code（engines.vscode ≥ 1.85） |
| 系统 |
当前装机脚本以 Windows 为主 |
| DevEco Studio |
本机已安装，并能在终端使用 hvigorw / ohpm / hdc |
| 工程 |
打开含根目录 build-profile.json5 的鸿蒙工程（多根工作区时自动选中含该文件的文件夹） |
建议将 DevEco 的 toolchains、ohpm 等加入 PATH，或设置环境变量 DEVECO_HOME / DEVECO_PATH。
快速开始
- 从扩展市场搜索并安装 DevEco Build Tool（扩展 ID：
haoyuyao.harmonyos-deveco）。
- 用 Cursor 打开鸿蒙工程根目录（含
build-profile.json5、hvigorw）。
- 打开左侧 DevEco 工具栏，点击底部 一键初始化（或命令面板：
DevEco Build Tool: 一键初始化本机配置）。
- bundleName / Ability 默认从工程读取（
AppScope/app.json5、entry 的 mainElement）；也可在工具栏 设置 里覆盖。
- 连接真机；多设备时在工具栏点设备列表选目标，或装机前会弹出选择。
- 推荐日常流程：
- 配置模块列表 或 应用 DevEco 预设
- 改完代码后优先用 增量构建并安装（只编受影响包）
- 全量多包仍用 Multi 构建并安装
工具栏说明
| 区域 |
作用 |
| 构建模式 |
切换 debug / release |
| Multi Deploy |
增量构建并安装、Multi 全量构建/装机、配置/应用模块列表 |
| 常用（整包） |
assembleApp 整包构建与安装、启动应用 |
| 构建 |
ohpm install、Sync、Clean、指定模块构建 |
| 设备 |
刷新 / 选择目标设备、停止应用、检查工具链 |
增量构建并安装
装机成功后会把当前工作区整仓 git write-tree 指纹写入 .git/harmonyos-last-deploy.tree。
之后增量优先用 diff-tree(上次装机, 当前) 找变更（改过又改回也会再编）；尚无快照时回退到 git 相对 HEAD（含已暂存、未暂存、未跟踪）：
- 按
build-profile 的 srcPath 映射到所属模块
- 若变更在 HAR：沿
oh-package.json5 依赖传递展开到最终 HAP/HSP（如 pdf_core → viewer → component_pdf）
- 与 Multi Deploy 模块列表求交（HAR 本身不在列表中是正常的；
wpsdriver 等测试模块若不在列表则不会编）
- 仅构建并安装这些 HAP/HSP（不会仅为锁定而强制带上未变更的
entry）
- 弹出确认对话框后执行，管线与 Multi 装机相同（
installMulti → 启动）
工程需是 git 仓库；无变更或变更落在无法映射到可安装包时，会提示原因。
Multi Deploy 与整包的区别
|
增量构建并安装 |
Multi 构建并安装 |
构建并安装（整包） |
| 命令形态 |
同 Multi，但模块由「上次装机 write-tree / git」推断 |
--mode module + assembleHap assembleHsp |
assembleApp |
| 适用场景 |
日常改几处代码后快速装机 |
日常全量多包，接近 DevEco Run |
完整打包 / 发版验证 |
| 模块范围 |
变更影响的 entry / feature / shared |
你勾选的 entry / feature / shared |
工程整包产物 |
配置模块时：
- 仅列出
module.json5 中 type 为 entry / feature / shared 的模块
- 必选模块默认锁定
entry（可通过 harmonyos.requiredDeployModules 调整）
- 「应用 DevEco 预设」会用内置常用模块名与当前工程
build-profile 求交；不同工程请再按需勾选保存
配置项
在工作区 .vscode/settings.json 或用户设置中配置（也可用工具栏 设置 / 一键初始化）：
| 配置键 |
说明 |
默认示例 |
harmonyos.devecoHome |
DevEco Studio 安装根目录 |
D:\DevEco Studio |
harmonyos.sdkHome |
SDK 根目录；空则用 {devecoHome}\sdk |
|
harmonyos.defaultBuildMode |
debug / release |
debug |
harmonyos.defaultProduct |
product 名 |
default |
harmonyos.bundleName |
应用包名；留空则读 AppScope/app.json5 |
（自动） |
harmonyos.targetDevice |
目标设备 UDID；多机装机用 |
空则自动选/弹窗 |
harmonyos.deployModules |
Multi Deploy 模块名列表 |
[]（空则用预设求交） |
harmonyos.requiredDeployModules |
必选/锁定模块 |
["entry"] |
harmonyos.useDaemon |
Multi 是否使用 --daemon |
false |
harmonyos.showStatusBar |
是否显示状态栏入口 |
true |
路径探测顺序：已配置且存在的 devecoHome → DEVECO_HOME / DEVECO_PATH → 常见安装目录。
初始化还会把 harmony-deploy.ps1 同步到工作区 .vscode/（用于真机 bm install / 启动 / Multi 装机）。
快捷键
| 快捷键 |
命令 |
Ctrl+Shift+H |
Multi 构建并安装 |
Ctrl+Shift+Alt+H |
打开 DevEco Build Tool 工具栏 |
也可在命令面板搜索 DevEco Build Tool 使用全部命令。
常见问题
工具栏提示未找到可部署模块
确认工作区根目录存在 build-profile.json5，且模块在 module.json5 中声明为 entry / feature / shared。
装机失败 / 找不到 signed hap
先成功完成 Multi 或整包构建；确认设备已连接（hdc list targets）；必要时重新执行 一键初始化 同步装机脚本。
java / ohpm / hdc 找不到
将 DevEco 自带 JBR、ohpm、toolchains 加入 PATH，或设置 JAVA_HOME 指向 DevEco 的 jbr，然后新开终端 / Reload Window。
构建偶发缓存异常
先 Clean / Sync；Multi Deploy 可保持 harmonyos.useDaemon 为 false，或按需开启以更接近 DevEco。
多根工作区
扩展会优先选择含 build-profile.json5 的文件夹作为工程根。
隐私与行为说明
- 扩展仅在本地调用本机 CLI 与工作区文件，不上传工程代码。
- 配置默认写入当前工作区（便于每人本机路径不同）。
反馈与许可
- 扩展 ID：
haoyuyao.harmonyos-deveco
- License：MIT（见
LICENSE）
欢迎在使用中反馈问题与改进建议。
