OHCodium for OpenHarmony

OHCodium 是面向 OpenHarmony/HarmonyOS PC 的 VSCodium 社区移植。本仓库把 VSCodium 应用层、OpenHarmony 适配补丁和 Electron HAP 外壳分开维护：开发者在一台 x86_64 Linux 主机上准备并编译 VSCodium，再把生成的 resources/app 注入空 HAP 工程，最后构建、签名并安装到 ARM64 HarmonyOS PC。

当前开发基线为 VSCodium 1.121.03429。补丁按该版本对应的 Code OSS 1.121.0 制作，不保证可以直接用于其他版本。

1. 当前边界

本仓库直接包含：

ohos_hap/：不含 VSCodium 应用层的 Electron HAP 空包；
patches/vscodium/：按编号顺序应用的 OpenHarmony 原子补丁；
Electron 运行资源、OpenHarmony ARM64 .so 和原生 Node 模块；
electron.hnp、rg.hnp 和 unzip.hnp；
OHCodium 分层应用图标和 Workbench 品牌图标补丁。

本仓库不跟踪：

已编译的 VSCodium resources/app；
MKCode Remote - SSH、MKCode Server 或其他远程开发实现；
Agents Window、MKCode Agent、OpenCode、Bun 或相关 HNP；
CMake、Make 等额外工具链。

当前固定版本如下：

组件	版本
VSCodium	`1.121.03429`
VSCodium commit	`eb967d7bffbcbaec6f9aa89ef7515b3cfe46dd0b`
Code OSS	`1.121.0`
Code OSS commit	`987c9597516278c9fcf10d963a0592ce1384ab93`
Node.js	`22.22.1`
Electron 运行时	`37.2.0`
Node module ABI	`136`
设备架构	OpenHarmony ARM64
HAP target SDK	HarmonyOS `6.0.0(20)`

2. 构建模型

本文只使用一台 Linux 开发主机，不再区分“本地电脑”和“远程编译机”：

克隆本仓库并拉取 Git LFS 运行资源
        |
        v
获取 VSCodium 1.121.03429 和 Code OSS 1.121.0
        |
        v
应用 OHCodium 原子补丁并编译 app-only min 产物
        |
        v
把 resources/app 注入 ohos_hap
        |
        v
使用 HarmonyOS Command Line Tools 构建、签名和安装 HAP

Linux 主机负责完整流程。VSCodium 构建阶段生成 JavaScript、内置扩展和应用资源；设备需要的 ARM64 Electron、.node 与命令行程序由空 HAP 工程提供，不能使用 Linux x86_64 主机上生成的原生二进制替代。

3. 获取本仓库

本项目不再提供单独的 OHCodium 空包 ZIP。HAP 模板、OpenHarmony 补丁、 Electron 运行资源、HNP 和 ARM64 原生模块都直接保存在本仓库中。大型二进制使用 Git LFS 管理，因此克隆前需要先安装 Git LFS。

先在本机启用 Git LFS，再使用当前代码托管页面提供的 Clone URL 克隆仓库。进入仓库根目录后拉取完整运行资源：

git lfs install
git lfs pull

克隆后的结构如下：

ohos-vscodium/
├── README.md
├── patches/
│   └── vscodium/
│       ├── 0001-....patch
│       └── 0015-....patch
└── ohos_hap/
    ├── AppScope/
    ├── electron/
    ├── hnp/
    └── web_engine/

配置后续命令使用的路径，并先检查空包是否完整：

export OHCODIUM_ROOT="$PWD"
export HAP_ROOT="$OHCODIUM_ROOT/ohos_hap"
export OHCODIUM_BUILD_ROOT="$(dirname "$OHCODIUM_ROOT")/ohcodium-build"
mkdir -p "$OHCODIUM_BUILD_ROOT"

test -f "$HAP_ROOT/build-profile.json5"
test -f "$HAP_ROOT/electron/libs/arm64-v8a/libelectron.so"
test -f "$HAP_ROOT/electron/libs/arm64-v8a/node_modules/node-pty/build/Release/pty.node"
test -f "$HAP_ROOT/hnp/arm64-v8a/electron.hnp"
test -f "$HAP_ROOT/hnp/arm64-v8a/rg.hnp"
test -f "$HAP_ROOT/hnp/arm64-v8a/unzip.hnp"
test ! -e "$HAP_ROOT/hnp/arm64-v8a/mkcode-agent.hnp"
test ! -e "$HAP_ROOT/web_engine/src/main/resources/resfile/resources/app/package.json"

最后一个检查应当成功，因为仓库不跟踪生成后的 VSCodium 应用层；开发者需要在后续步骤中自行构建并放入指定位置。resources/app、签名材料和 HAP 构建产物均已被 .gitignore 排除，不应提交到公开仓库。

4. 准备 Linux 构建环境

建议使用 Ubuntu 22.04/24.04 或对应版本的 Debian，主机至少具备：

x86_64 CPU，建议 16 个逻辑核心；
16 GB 内存，建议 32 GB；
35 GB 可用磁盘空间；
可访问 VSCodium、Code OSS、npm 和 HarmonyOS 工具下载源的网络。

安装基础依赖：

sudo apt-get update
sudo apt-get install -y \
  build-essential ca-certificates curl git git-lfs jq pkg-config python3 rsync \
  unzip zip zstd fakeroot rpm dpkg \
  libx11-dev libxkbfile-dev libsecret-1-dev libkrb5-dev \
  openjdk-17-jdk

确认 JDK：

java -version
javac -version

两者都应报告 JDK 17。若系统同时安装了多个 JDK，应将 JAVA_HOME 指向 JDK 17，而不是 JDK 8、11 或 21。

安装 Node.js 22.22.1

VSCodium 基线要求 Node.js 22.22.1。可以使用 nvm 或其他版本管理器，下面以 nvm 为例：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
nvm install 22.22.1
nvm use 22.22.1

node --version
npm --version

node --version 必须输出 v22.22.1。不要设置 npm_config_arch=arm64：VSCodium 的 npm 依赖是在 x86_64 Linux 主机上安装和编译，设备侧 ARM64 模块由 HAP 空包单独提供。

5. 配置 HarmonyOS Linux 命令行工具

Linux 不使用 DevEco Studio 图形界面，需要安装 HarmonyOS Command Line Tools，并确保其中包含 HarmonyOS SDK 6.0.0(20)。将官方工具解压到固定目录后，令 DEVECO_CLI_CLT_PATH 指向 Command Line Tools 根目录：

export DEVECO_CLI_CLT_PATH=/opt/harmonyos/command-line-tools
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"

路径应按实际安装位置修改。Linux 上 devecocli 不会从 DevEco Studio 的默认目录自动发现工具，因此 DEVECO_CLI_CLT_PATH 不能省略。

安装 DevEco CLI：

npm install -g @deveco/deveco-cli
devecocli --version

当前教程验证的 CLI 主版本为 1.x。先检查 CLI、Command Line Tools 和空包工程是否存在：

cd "$HAP_ROOT"
devecocli build --help
test -d "$DEVECO_CLI_CLT_PATH"
test -f "$HAP_ROOT/build-profile.json5"

Command Line Tools 与工程的完整匹配会在第 13 节首次构建时验证。此时缺少签名或 resources/app 属于尚未完成后续步骤，不应通过删除权限、HNP 声明或 ARM64 库来绕过检查。

6. 中国大陆网络镜像（按需）

如果开发主机位于中国大陆，可在当前终端设置 npm 和 Electron 镜像：

export npm_config_registry=https://registry.npmmirror.com
export npm_config_disturl=https://npmmirror.com/mirrors/electron
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export NODE_OPTIONS=--max-old-space-size=16384

截至 2026-08-10，VSCodium 的 GitCode 镜像和 ghproxy.net 可按下面组合使用：前者只负责克隆 VSCodium，后者供 get_repo.sh 获取 Code OSS 及其他 GitHub 依赖。不要让 VSCodium 的大 Git pack 也经过 ghproxy.net，实测容易在传输末尾发生 curl 18 / early EOF。

export VSCODIUM_REPOSITORY_URL=https://gitcode.com/gh_mirrors/vs/vscodium.git
export GITHUB_MIRROR=https://ghproxy.net
export VSCODE_GITHUB_MIRROR=https://ghproxy.net
git config --global url."$GITHUB_MIRROR/https://github.com/".insteadOf \
  'https://github.com/'

镜像可用性会变化；开始完整构建前应先运行 git ls-remote 验证目标 tag。不需要镜像时不要执行 Git URL 重写。构建完成后也可以删除该全局配置：

git config --global --unset-all \
  url."$GITHUB_MIRROR/https://github.com/".insteadOf

7. 获取并校验 VSCodium

在独立构建目录中克隆固定版本，避免把 VSCodium 源码和主机构建产物提交到 OHCodium 仓库：

export VSCODIUM_ROOT="$OHCODIUM_BUILD_ROOT/vscodium"
export VSCODIUM_REPOSITORY_URL="${VSCODIUM_REPOSITORY_URL:-https://github.com/VSCodium/vscodium.git}"

git clone --branch 1.121.03429 --depth 1 \
  "$VSCODIUM_REPOSITORY_URL" "$VSCODIUM_ROOT"

git -C "$VSCODIUM_ROOT" rev-parse HEAD
cat "$VSCODIUM_ROOT/upstream/stable.json"

VSCodium commit 必须是：

eb967d7bffbcbaec6f9aa89ef7515b3cfe46dd0b

upstream/stable.json 必须指向：

{
  "tag": "1.121.0",
  "commit": "987c9597516278c9fcf10d963a0592ce1384ab93"
}

任一版本不一致都应停止。不要把为 1.121.0 制作的补丁强行套到更新的 Code OSS 源码。

8. 生成 Code OSS 源码树

运行 VSCodium 自己的准备流程：

cd "$VSCODIUM_ROOT"

export SHOULD_BUILD=yes
export SHOULD_BUILD_REH=no
export CI_BUILD=no
export OS_NAME=linux
export VSCODE_ARCH=x64
export VSCODE_QUALITY=stable
export RELEASE_VERSION=1.121.03429

. ./get_repo.sh
./prepare_vscode.sh

这里的 OS_NAME=linux 和 VSCODE_ARCH=x64 描述的是当前构建主机，不是最终设备。OpenHarmony ARM64 目标由后面的 OHCodium 构建补丁添加。

准备完成后：

export VSCODE_SOURCE="$VSCODIUM_ROOT/vscode"

test -f "$VSCODE_SOURCE/package.json"
test -f "$VSCODE_SOURCE/node_modules/typescript/lib/_tsserver.js"
test -f "$VSCODE_SOURCE/node_modules/node-pty/lib/utils.js"
git -C "$VSCODE_SOURCE" log --oneline -3

prepare_vscode.sh 会获取 Code OSS、应用 VSCodium 自身补丁、生成 product.json 并安装依赖。OHCodium 补丁必须在它完成后应用，因为 0013 和 0014 需要修改已经安装好的依赖文件，0015 负责生成 OHCodium 产品名称、数据目录和 URL protocol。

9. 应用 OHCodium 原子补丁

补丁文件名带四位序号，必须按 0001 到 0015 的顺序应用：

export OHCODIUM_PATCH_ROOT="$OHCODIUM_ROOT/patches/vscodium"

for patch_file in "$OHCODIUM_PATCH_ROOT"/*.patch; do
  echo "Applying $(basename "$patch_file")"
  git -C "$VSCODE_SOURCE" apply --check "$patch_file"
  git -C "$VSCODE_SOURCE" apply "$patch_file"
done

git -C "$VSCODE_SOURCE" diff --check

不要跳过前置补丁后单独应用后续补丁，也不要重复执行这个循环。需要重来时，删除 vscodium/ 工作目录并从第 7 节重新开始，避免把依赖目录恢复成不完整状态。

确认关键适配已经进入源码树：

rg -n "vscode-openharmony|platform: 'openharmony'" \
  "$VSCODE_SOURCE/build/gulpfile.vscode.ts"
rg -n "case .*openharmony|/data/app/bin" \
  "$VSCODE_SOURCE/src/main.ts" \
  "$VSCODE_SOURCE/node_modules/typescript/lib/_tsserver.js"

10. 编译 OpenHarmony app-only min 应用

先执行 TypeScript 检查，再执行完整 min 构建：

cd "$VSCODE_SOURCE"

export NODE_OPTIONS=--max-old-space-size=16384
export BUILD_SOURCEVERSION="$(git rev-parse HEAD)"

npm run compile-check-ts-native
npm run gulp vscode-openharmony-arm64-min

vscode-openharmony-arm64-min 只生成 Code OSS/VSCodium 应用层，不下载或嵌入桌面版 Electron。输出目录为：

<VSCODIUM_ROOT>/VSCode-openharmony-arm64/resources/app/

检查输出：

export VSCODIUM_OUTPUT="$VSCODIUM_ROOT/VSCode-openharmony-arm64"

test -f "$VSCODIUM_OUTPUT/resources/app/package.json"
test -f "$VSCODIUM_OUTPUT/resources/app/product.json"
test -f "$VSCODIUM_OUTPUT/resources/app/out/main.js"
test -d "$VSCODIUM_OUTPUT/resources/app/extensions"

这里出现的 Linux x86_64 .node 只属于构建主机。运行时补丁会让 OpenHarmony 从 HAP 的 ARM64 库目录加载对应模块。

11. 注入 HAP 空包

只替换 resources/app，不要覆盖空包中的 Electron 资源、HNP、ArkTS 源码或 ARM64 库：

export APP_ROOT="$HAP_ROOT/web_engine/src/main/resources/resfile/resources/app"

mkdir -p "$APP_ROOT"
rsync -a --delete \
  "$VSCODIUM_OUTPUT/resources/app/" \
  "$APP_ROOT/"

注意：rsync --delete 的目标必须精确为上面的 APP_ROOT。执行前可以输出并人工确认路径：

printf '%s\n' "$APP_ROOT"
test "$APP_ROOT" = \
  "$HAP_ROOT/web_engine/src/main/resources/resfile/resources/app"

注入后检查应用和设备原生模块同时存在：

test -f "$APP_ROOT/out/main.js"
test -f "$APP_ROOT/product.json"
test -f "$HAP_ROOT/electron/libs/arm64-v8a/node_modules/@vscode/spdlog/build/Release/spdlog.node"
test -f "$HAP_ROOT/electron/libs/arm64-v8a/node_modules/@vscodium/native-keymap/build/Release/keymapping.node"
test -f "$HAP_ROOT/electron/libs/arm64-v8a/node_modules/@parcel/watcher/build/Release/watcher.node"

12. 配置签名

ohos_hap/build-profile.json5 默认不携带任何开发者的私钥、证书或 Profile。真实设备安装前必须生成自己的签名，而且签名 Profile 需要覆盖工程声明的 ACL 权限。

使用 DevEco CLI 自动生成调试签名：

cd "$HAP_ROOT"
devecocli auth login
devecocli auth status
devecocli device list
devecocli signature generate --product default

也可以使用已有的 .p12、.cer 和 .p7b 手动配置 build-profile.json5。签名材料包含私钥、密码和本机绝对路径，不应提交到公开仓库。仓库的 .gitignore 会排除常见证书与密钥文件，但提交前仍应检查 git diff --cached。

13. 构建 HAP

首次构建或更换应用树后执行干净构建：

cd "$HAP_ROOT"
devecocli build clean
devecocli build --product default --build-mode debug

输出通常位于：

ohos_hap/electron/build/default/outputs/default/

有签名配置时应生成 electron-default-signed.hap。发布前可以把 --build-mode debug 改为 --build-mode release，但必须先完成 debug 包的设备回归。

构建完成后检查包结构：

export FINAL_HAP="$HAP_ROOT/electron/build/default/outputs/default/electron-default-signed.hap"

test -f "$FINAL_HAP"
unzip -tqq "$FINAL_HAP"
unzip -l "$FINAL_HAP" | rg \
  'electron\.hnp|rg\.hnp|unzip\.hnp|resources/app/out/main\.js'

四项都必须存在。若应用能打包但 HAP 中缺少 HNP，应停止安装并检查所用 Command Line Tools/Hvigor 是否支持工程的 hnpPackages 声明。

14. 安装到 HarmonyOS PC

连接设备后先查看序列号：

cd "$HAP_ROOT"
devecocli device list

安装已经构建好的包并启动：

devecocli run \
  --module electron \
  --skip-build \
  --device <DEVICE_SERIAL>

默认采用覆盖安装以保留用户数据。只有设备返回签名不一致时，才使用 --uninstall 先卸载旧包：

devecocli run \
  --module electron \
  --skip-build \
  --uninstall \
  --device <DEVICE_SERIAL>

卸载会清除应用数据，不应作为每次部署的默认参数。

15. 最小回归清单

首次启动后至少验证：

应用名称和分层图标显示为 OHCodium。
欢迎页和标题栏显示 OHCodium 图标。
原生最小化、最大化和关闭按钮可用，关闭后进程退出。
可以打开本地文件夹，创建、保存、删除文件；普通删除进入系统回收站。
集成终端默认打开 zsh，并保留 sh、bash 选项。
工作区文本搜索能够调用 rg.hnp。
打开 .ts 文件后 TypeScript Language Service 不崩溃。
键盘快捷键、文件监听、Git 和扩展安装/卸载工作正常。

查看最近错误和崩溃：

devecocli log --level E --from 5m --tail 300 \
  --bundle-name com.openharmony.vscodium \
  --device <DEVICE_SERIAL>

devecocli log --crash \
  --bundle-name com.openharmony.vscodium \
  --device <DEVICE_SERIAL>

16. 常见问题

补丁无法应用

先核对 VSCodium tag、VSCodium commit 和 upstream/stable.json。如果 0013、0014 或 0015 报目标文件不存在，说明源码版本不匹配，或者 prepare_vscode.sh 没有完成依赖安装。不要使用 --reject 或手工忽略冲突。

Linux 找不到 DevEco Studio

Linux 使用 HarmonyOS Command Line Tools，不安装 DevEco Studio。确认：

printf '%s\n' "$DEVECO_CLI_CLT_PATH"
test -d "$DEVECO_CLI_CLT_PATH"

设备拒绝安装签名 HAP

确认 Profile 包含当前设备和工程所需 ACL 权限。若设备已经安装了另一个证书签名的 com.openharmony.vscodium，需要先备份数据，再使用 --uninstall 重新安装。

HAP 中找不到 HNP

不要继续测试。缺少 electron.hnp 时应用无法获得完整 Electron 运行环境；缺少 rg.hnp 或 unzip.hnp 时对应命令无法在沙箱内执行。应先检查 HAP ZIP 内容和 Hvigor 的 HNP 打包能力。

17. 更新版本

升级 VSCodium 时不能只修改版本字符串。至少需要：

固定新的 VSCodium tag、commit 和 Code OSS commit；
在新的 prepare_vscode.sh 干净源码树逐个重放并更新全部补丁；
对每个补丁执行 git apply --check 和 git diff --check；
完整运行 TypeScript 检查与 vscode-openharmony-arm64-min；
核对 Electron、Node ABI、ARM64 .node 和 HNP 兼容性；
重新构建签名 HAP并执行完整设备回归；
为最终 HAP 和其他发布产物重新生成 SHA-256。

任何平台、ABI、签名或 checksum 不匹配都应阻止发布。

Navigation Menu

Repository files navigation

OHCodium for OpenHarmony

1. 当前边界

2. 构建模型

3. 获取本仓库

4. 准备 Linux 构建环境

安装 Node.js 22.22.1

5. 配置 HarmonyOS Linux 命令行工具

6. 中国大陆网络镜像（按需）

7. 获取并校验 VSCodium

8. 生成 Code OSS 源码树

9. 应用 OHCodium 原子补丁

10. 编译 OpenHarmony app-only min 应用

11. 注入 HAP 空包

12. 配置签名

13. 构建 HAP

14. 安装到 HarmonyOS PC

15. 最小回归清单

16. 常见问题

补丁无法应用

Linux 找不到 DevEco Studio

设备拒绝安装签名 HAP

HAP 中找不到 HNP

17. 更新版本

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
ohos_hap		ohos_hap
patches/vscodium		patches/vscodium
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
openharmony-icon.svg		openharmony-icon.svg

Latest commit

History

Folders and files

Repository files navigation

OHCodium for OpenHarmony

1. 当前边界

2. 构建模型

3. 获取本仓库

4. 准备 Linux 构建环境

安装 Node.js 22.22.1

5. 配置 HarmonyOS Linux 命令行工具

6. 中国大陆网络镜像（按需）

7. 获取并校验 VSCodium

8. 生成 Code OSS 源码树

9. 应用 OHCodium 原子补丁

10. 编译 OpenHarmony app-only min 应用

11. 注入 HAP 空包

12. 配置签名

13. 构建 HAP

14. 安装到 HarmonyOS PC

15. 最小回归清单

16. 常见问题

补丁无法应用

Linux 找不到 DevEco Studio

设备拒绝安装签名 HAP

HAP 中找不到 HNP

17. 更新版本

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages