更多交流学习欢迎加入开源鸿蒙PC社区https://harmonypc.csdn.net/欢迎在PC社区平台申请新建项目https://atomgit.com/OpenHarmonyPCDeveloper猫哥的博客https://blog.csdn.net/qq8864一、概述本文档面向 OpenHarmony PC鸿蒙电脑开发者完整讲解Node.js 生态三方库鸿蒙化移植、本地验证测试、社区 PR 提交、流水线自动发布 NPM 包全链路流程同时说明补丁Patch编写、上游社区贡献规范。涉及两大核心代码仓库移植验证工具仓atomgit.com/OpenHarmonyPCDeveloper/JavaScript_Package_For_HarmonyOSSKILL 工具集社区三方库托管仓github.com/ohos-npm-ports/ohos-npm-portsohos-ports 社区仓库整体链路SKILL 工具本地移植验证 → Fork 社区仓库编写移植脚本与补丁 → 提交 PR 至上游社区仓库 → 管理员合入 PR 触发 CI 流水线 → 自动打包发布至npmjs.com社区组织包。二、前置准备工作2.1 环境与账号准备Git 与代码平台账号AtomGit 账号用于拉取 SKILL 移植工具仓库GitHub 账号用于 Forkohos-npm-ports社区仓库、提交 Pull RequestGit 基础环境配置全局用户名、邮箱支持 Git 拉取、提交、推送操作。鸿蒙 PC 开发环境完成 OpenHarmony PC 编译环境部署具备 Node.js 运行、跨平台编译能力用于执行移植后三方库的功能测试。2.2 仓库代码拉取拉取 SKILL 移植工具仓库本地移植验证核心gitclone https://atomgit.com/OpenHarmonyPCDeveloper/JavaScript_Package_For_HarmonyOS.gitGitHub Fork 社区仓库访问https://github.com/ohos-npm-ports/ohos-npm-ports点击页面Fork按钮将社区仓库复制至个人 GitHub 账号下作为本地开发、编写移植脚本的个人工作仓。三、步骤 1基于 SKILL 工具完成三方库鸿蒙化移植与本地验证SKILL 工具仓库提供完整自动化工具链支持批量验证调度、单库单独移植、源码分析、补丁生成、自动化测试五大核心能力是移植工作的起点。3.1 SKILL 工具目录结构说明JavaScript_Package_For_HarmonyOS/ └── skills/ ├── 批量验证调度 # 批量批量处理多个三方库移植任务 ├── 单库验证调度 # 针对单个目标三方库单独执行移植流程 ├── 分析 # 解析目标NPM库源码识别平台兼容性问题 ├── 迁移 # 自动生成鸿蒙适配Patch补丁、构建脚本 └── 测试 # 自动化执行移植后三方库单元测试、功能验证3.2 完整移植操作流程目标库兼容性分析使用skills/分析模块输入需要移植的 NPM 三方库名称与版本工具自动扫描源码识别 Linux/Windows/macOS 平台硬编码逻辑定位系统 API、文件路径、编译脚本中不兼容鸿蒙 PC 的代码输出兼容性问题清单作为补丁编写依据。执行源码迁移生成 Patch 补丁调用skills/迁移模块基于上一步分析结果自动生成适配鸿蒙 PC 的源码修改补丁Patch 文件同时生成配套构建脚本build.sh。本地自动化验证测试单库移植场景使用单库验证调度批量移植多个库使用批量验证调度执行skills/测试模块运行三方库完整测试用例验证补丁修改后库功能正常输出完整测试报告必须确保全部测试用例通过方可进入社区贡献环节。3.3 本阶段交付产物完成 SKILL 工具全流程后将获取以下可提交至社区仓库的文件目标三方库独立目录存放于ports/根目录下patches/目录存放适配鸿蒙 PC 的源码补丁文件tests/目录存放验证该库可用性的自动化测试用例build.sh鸿蒙 PC 平台专属编译、打包构建脚本。四、步骤 2个人仓库开发编写移植脚本并本地二次验证4.1 个人 Fork 仓库目录规范ohos-npm-ports仓库核心目录为ports/所有移植的 Node.js 三方库统一在此目录下管理标准目录结构示例ohos-npm-ports/ ├── .github/workflows/ci.yml # CI流水线自动构建配置文件 └── ports/ ├── 三方库1/ │ ├── patches/ # 鸿蒙适配补丁 │ ├── tests/ # 测试用例 │ └── build.sh # 构建脚本 ├── 三方库2/ └── 三方库3/4.2 本地开发与二次验证将 SKILL 工具生成的三方库完整目录复制至个人 Fork 仓库的ports/目录下在本地个人仓库环境中执行build.sh构建脚本本地完整复现编译、打包流程运行tests/内测试用例二次确认移植库在鸿蒙 PC 环境下功能、兼容性无问题本地 Git 提交所有新增 / 修改文件推送至个人 GitHub 远程仓库。五、步骤 3向社区上游仓库提交 PR完成社区贡献5.1 PR 提交操作流程访问个人 Fork 后的 GitHub 仓库页面点击Compare pull request按钮创建 PRPR 标题规范[移植] 三方库名称版本号 鸿蒙PC适配PR 描述必填内容移植目标库版本SKILL 工具兼容性分析结论Patch 补丁修改内容说明本地完整测试结果测试用例通过率提交 PR 至上游社区仓库ohos-npm-ports/ohos-npm-ports。5.2 PR 审核规范社区 Committer 会校验目录结构规范、Patch 补丁合理性、build.sh可执行性、测试用例完整性若审核存在问题根据 Committer 反馈修改个人仓库代码推送更新至 PR直至审核通过。六、步骤 4PR 合入后自动流水线构建与 NPM 包发布CI 流水线自动触发PR 审核通过后社区 Committer 执行合入操作仓库根目录.github/workflows/ci.yml配置的 GitHub Action 流水线自动启动流水线执行流程拉取所有 ports 目录下三方库源码与补丁逐个执行build.sh完成鸿蒙 PC 平台打包构建运行自动化测试校验构建产物可用性自动发布至 NPM 官方仓库CI 流水线全部步骤执行成功后系统自动将打包完成的鸿蒙适配三方库发布至npmjs.com中ohos-ports社区组织下的packages包目录开发者可直接通过 NPM 安装使用鸿蒙 PC 适配版本。七、上游补丁贡献补充说明7.1 补丁Patch编写原则最小修改原则仅修改导致鸿蒙 PC 不兼容的代码不改动上游库原生逻辑平台隔离原则通过系统判断宏、环境变量区分鸿蒙 PC 与其他平台保证补丁不影响 Linux/macOS/Windows 原生运行补丁可追溯Patch 文件头部注释标注修改原因、适配鸿蒙 PC 版本、对应 SKILL 工具分析单号。7.2 向上游开源库提交原生补丁进阶贡献除了在ohos-npm-ports社区仓库维护鸿蒙专属 Patch 外可将兼容性补丁向上游 NPM 库原仓库提交 PR实现原生支持鸿蒙 PC基于上游库源码剥离仅鸿蒙平台相关逻辑编写通用跨平台兼容补丁向上游开源仓库提交 PR说明补丁用于完善 Linux 类嵌入式 / PC 系统兼容性若上游合入补丁后续鸿蒙 PC 移植可移除本地patches/目录直接使用上游原生版本简化维护成本。八、常见问题说明SKILL 工具移植测试不通过返回skills/分析模块重新扫描源码补充遗漏的平台兼容问题重新生成 Patch 并复测CI 流水线构建失败检查build.sh脚本权限、系统依赖、补丁文件路径是否规范本地复现构建流程修复问题后更新 PRPR 审核被驳回对照 Committer 评审意见修复目录结构、测试用例缺失、补丁冗余等问题后重新推送更新。九、流程总结整体贡献链路闭环SKILL工具本地移植分析 → 生成Patch与测试用例 → Fork社区仓库本地开发验证 → 提交PR至上游ohos-ports社区 → Committer合入PR触发CI流水线 → 自动构建并发布鸿蒙适配NPM包该流程标准化了鸿蒙 PC Node.js 三方库移植工作同时支持开发者向上游开源社区贡献通用跨平台补丁完善 OpenHarmony PC JavaScript 生态。
