简介本资源为OpenHarmony 5.1.0 full sdk公版中面向Windows 64位平台的JavaScript SDK发布包属于正式Release版本适合在Windows环境下开发、调试与测试OpenHarmony应用的开发者使用。压缩包共约2000个文件整体约56.67MB以1204个js脚本、611个md说明文档、169个json配置、10个txt及少量html、sh文件为主涵盖JavaScript API接口、开发工具、示例代码与运行时环境等模块便于快速上手与查阅。目前已有510人学习下载。通过该SDK读者可获取完整的JavaScript调用能力、配套文档与示例工程降低学习成本提升在Windows平台构建OpenHarmony应用的效率也为进一步参与OpenHarmony生态开发打下基础。1. 拿到 OpenHarmony 5.1.0 full sdk 的 js-windows-x64 包先别急着解压如果你在 Windows 上做 OpenHarmony 的 JS/TS 应用开发大概率绕不开一个东西full sdk。它和那种只带接口声明的精简包不一样里面塞了完整的 API 实现、工具链、预览器运行时还有一堆你平时不会主动打开、但缺了就报错的组件。这次流出来的是js-windows-x64-5.1.0.107-Release这一部分版本号锁在 5.1.0.107Release 构建平台是 Windows x64语言栈是 JS。很多人第一次拿到这种包习惯性双击解压、随便找个目录一扔然后在 IDE 里配路径结果 DevEco Studio 死活认不出来或者认出来了但预览器起不来。问题往往不在包本身而在目录结构和环境变量的对应关系上。这篇笔记就按我实际拆包、配环境、跑通一个最小 JS 页面的顺序来写把 full sdk 里 js-windows-x64 这一支的用法、参数和几个容易翻车的点讲清楚。适合正在配 OpenHarmony 开发环境、或者手里已经有一个 full sdk 包但不确定怎么接进工具链的人。2. full sdk 与 js-windows-x64 分支先搞清你手里是什么2.1 full sdk 和 public sdk 的差别在哪OpenHarmony 的 SDK 在分发上大致分两种形态。一种是 public sdk只包含对外暴露的接口声明和少量运行时体积小适合做纯接口校验和轻量编译。另一种就是 full sdk它把 API 的实现、系统能力、工具链、甚至部分系统应用的编译产物都打进去了。你拿到的js-windows-x64-5.1.0.107-Release属于后者而且是专门给 Windows x64 主机、面向 JS 语言栈的那一支。这个差别直接决定了你能干什么。用 public sdk你写个ohos.app.ability.UIAbility的导入编译器能过但真跑到预览器或者模拟器上底层实现是缺的运行时就报找不到模块。full sdk 里带了ets、js、native等几个子目录其中js目录下就是 JS 运行时的完整支撑。所以如果你要做的是带 UI 预览、带真实 API 调用的开发full sdk 是必须的public sdk 只能算个占位。2.2 js-windows-x64 这个命名拆开看包名js-windows-x64-5.1.0.107-Release其实把四个关键信息压在一起了。js表示这一支面向的是 JS/TS 语言栈对应的还有ets和nativewindows是宿主平台不是目标设备平台目标设备仍然是 OpenHarmony 设备或模拟器x64是宿主机的架构Apple Silicon 上跑 Windows 虚拟机的话要注意架构匹配5.1.0.107是 SDK 版本号Release表示这是发布构建不是 Debug 或 Beta。这里有个常见的误解有人以为windows意味着只能开发 Windows 应用。不是的它只是说你的开发机是 Windows编译出来的 HAP 包还是跑在 OpenHarmony 设备上。真正决定目标平台的是你在build-profile.json5里配的targets和deviceType。2.3 目录结构里哪些是必须的解压之后根目录下一般能看到这么几个东西目录/文件作用是否必须ets/ArkTS 接口声明与实现是js/JS API 声明与运行时是native/Native API 头文件与库按需toolchains/编译、打包、签名工具是previewer/预览器运行时做 UI 预览时是oh-uni-package.jsonSDK 元信息版本与路径描述是oh-uni-package.json这个文件特别关键DevEco Studio 就是靠它来识别 SDK 版本的。如果你手动挪动了子目录这个文件里的相对路径就对不上了工具链会直接报SDK component missing。我一般建议整个包解压后不要再拆散要挪就整包挪。3. 把 full sdk 接进 DevEco Studio路径、版本与校验3.1 解压位置的选择与目录规范Windows 上解压路径尽量短、不要带中文、不要带空格。常见做法是放在D:\ohos-sdk\下面然后按版本号建子目录比如D:\ohos-sdk\5.1.0.107\。这样做的原因是工具链里有些脚本对路径长度敏感路径太深或者含空格时hvigor调node执行编译会莫名其妙失败报的还是跟路径无关的错属于典型的玄学问题。解压命令用 PowerShell 或者 7-Zip 都行关键是保持目录层级。假设你拿到的是一个压缩包解压后应该直接看到ets、js、toolchains这些目录而不是再套一层。如果套了一层进 DevEco Studio 配路径时要指到里面那一层。# 以 PowerShell 为例解压到指定目录 Expand-Archive -Path D:\downloads\js-windows-x64-5.1.0.107-Release.zip -DestinationPath D:\ohos-sdk\5.1.0.107\ # 解压后确认目录结构 Get-ChildItem D:\ohos-sdk\5.1.0.107\ | Select-Object Name这段命令做两件事解压和列目录。-DestinationPath后面的路径就是最终 SDK 根目录列目录是为了确认oh-uni-package.json在不在这一层。如果列出来只有一个同名文件夹说明压缩包多套了一层配路径时要再进一级。3.2 在 DevEco Studio 里配置 SDK 路径打开 DevEco Studio进File Settings OpenHarmony SDK不同小版本菜单名可能略有差异有的叫SDK Manager。在SDK Location里填你刚才解压的根目录比如D:\ohos-sdk\5.1.0.107\。填完之后工具会去读oh-uni-package.json读到了就会在列表里显示5.1.0.107这个版本并且把ets、js、toolchains等组件的状态标成已安装。如果状态显示为未安装或者版本号是空的先检查三件事路径是不是指到了含oh-uni-package.json的那一层oh-uni-package.json里的apiVersion和version字段是否完整目录权限是否可读。这三条排查完九成以上的识别问题都能解决。3.3 用命令行校验 SDK 是否可用配完路径别急着建工程先用命令行验一下工具链能不能跑。进到toolchains目录找hvigorw或者相关的构建脚本跑一个版本查询。# 进入 toolchains 目录 cd D:\ohos-sdk\5.1.0.107\toolchains\ # 查看 hvigor 版本确认工具链可执行 .\hvigorw.bat --version # 查看 node 是否被工具链正确引用 .\node.exe --versionhvigorw.bat --version能打印出版本号说明工具链的入口脚本没问题。node.exe --version能打印说明工具链自带的 Node 运行时可用。这两步过了基本可以确定 SDK 的toolchains分支是完整的。如果hvigorw报找不到node多半是环境变量PATH里没有把工具链目录加进去或者hvigorw.bat里的相对路径被破坏了。提示不要用系统全局安装的 Node 去替换工具链自带的 Node。版本不匹配时hvigor编译会报一些跟语法无关的模块解析错误很难往回查。4. 用这份 SDK 跑通一个最小 JS 页面从建工程到预览4.1 建工程时的 SDK 选择与参数在 DevEco Studio 里新建工程模板选Empty Ability语言选JS注意不是 ArkTS。在Project SDK那一栏确认选的是5.1.0.107这个版本。Compile SDK Version和Compatible SDK Version都跟着选 5.1.0.107Device Type按你实际要跑的设比如phone或tablet。建完之后先别改代码直接点预览。如果预览器能起来并渲染出默认页面说明 full sdk 的previewer分支和js运行时都接对了。这一步是整个环境配置的试金石预览器起不来后面写多少代码都是白搭。4.2 一个最小页面的代码与结构在entry/src/main/js/default/pages/index/下面index.js和index.hml是核心。写一个带按钮和文本的最小交互// index.js export default { data: { count: 0 }, // 按钮点击时累加计数 onAdd() { this.count; } }!-- index.hml -- div classcontainer text classtitle{{ count }}/text button classbtn onclickonAdd加一/button /div/* index.css */ .container { display: flex; flex-direction: column; justify-content: center; align-items: center; width: 100%; height: 100%; } .title { font-size: 40px; color: #000000; } .btn { width: 200px; height: 60px; margin-top: 20px; }index.js里data是页面状态onAdd是事件处理函数this.count直接改状态框架会自动触发视图更新。index.hml里{{ count }}是数据绑定onclickonAdd把按钮点击绑到函数上。index.css用 flex 布局把内容居中width和height设成100%是为了占满预览器画布。4.3 预览器起不来时的排查顺序预览器报错时按这个顺序查先看previewer目录在不在 SDK 根目录下再看build-profile.json5里的compileSdkVersion是不是 5.1.0.107然后看oh-uni-package.json里的apiVersion和工程里配的是否一致。这三步覆盖了大部分预览失败的情况。还有一种情况是预览器进程起来了但白屏。这通常是js运行时没加载到检查entry/src/main/js/default/下的app.js是否存在以及config.json里的js入口路径是否写对。full sdk 的js分支对入口文件的命名和位置有约定挪动了就会白屏控制台还不一定报错。5. 避坑与常见问题版本、路径、架构的几笔血泪账5.1 现象SDK 识别成功但编译报模块找不到原因通常是ets和js两个分支的版本不一致。full sdk 包里这两个目录是配套的如果你从别处拷了一个ets目录过来混用oh-uni-package.json里的版本描述和实际文件对不上编译时模块解析就会失败。解决方法是整包替换不要单独换某个子目录。确认ets和js都来自同一个5.1.0.107的包oh-uni-package.json里的version字段和目录名一致。5.2 现象预览器启动后闪退日志里没有明显错误原因多半是宿主机的架构和 SDK 的x64不匹配。比如在 ARM 架构的 Windows 环境里跑 x64 的预览器进程能起来但渲染层初始化失败直接闪退日志还来不及写。解决办法是确认开发机是 x64 架构或者在兼容层里跑。如果是虚拟机检查虚拟机的 CPU 架构设置。这个坑比较隐蔽因为 IDE 本身能跑只有预览器崩容易误判成 SDK 损坏。5.3 现象hvigor 编译卡在某个任务不动原因是路径里有中文或空格导致node子进程的工作目录解析异常。表现是编译进度条卡住不报错也不结束。解决办法是把 SDK 和工程都挪到纯英文、无空格的短路径下比如D:\ohos-sdk\和D:\projects\。挪完之后清一下build缓存目录再重新编译。5.4 现象签名配置报错提示找不到签名工具原因是toolchains目录下的签名工具没有被正确引用或者PATH里混入了其他版本的签名工具。full sdk 的toolchains里带了配套的签名工具版本和 SDK 是绑定的。解决办法是在 DevEco Studio 的Build Signing Configs里确认签名工具路径指向当前 SDK 的toolchains目录不要用系统里其他位置的工具。如果之前配过别的版本先清掉再重新配。5.5 现象升级 SDK 后旧工程编译失败原因是compileSdkVersion和compatibleSdkVersion没有跟着改或者oh-package.json5里的依赖版本还是旧的。full sdk 升级时API 签名可能有变化旧代码里用到的接口如果被调整了编译就会报错。解决办法是先把工程里的 SDK 版本号统一改成新版本然后看编译报错具体指向哪个 API对照新版本的接口声明调整。不要盲目改代码先确认是版本没对齐还是接口真的变了。6. 进阶用 full sdk 的 native 分支做 JS 与 C 的混合调用full sdk 里除了js和ets还有一个native目录里面是 Native API 的头文件和库。这一支的用法是在 JS 侧通过ohos.napi相关的接口调用 C 函数C 侧用napi_module_register注册模块。这个能力在 public sdk 里是残缺的只有 full sdk 才带完整的头文件和链接库。具体做法是在工程的entry/src/main/cpp/下建CMakeLists.txt和 C 源文件然后在build-profile.json5里配externalNativeOptions把path指向CMakeLists.txt。C 侧写一个简单的加法函数// native_adder.c #include napi/native_api.h // 实现一个 JS 可调用的加法函数 static napi_value Add(napi_env env, napi_callback_info info) { size_t argc 2; napi_value args[2] {nullptr}; napi_get_cb_info(env, info, argc, args, nullptr, nullptr); double a, b; napi_get_value_double(env, args[0], a); napi_get_value_double(env, args[1], b); napi_value sum; napi_create_double(env, a b, sum); return sum; } // 注册模块导出 add 方法 static napi_value Init(napi_env env, napi_value exports) { napi_property_descriptor desc[] { {add, nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr} }; napi_define_properties(env, exports, 1, desc); return exports; } static napi_module demoModule { .nm_version 1, .nm_flags 0, .nm_filename nullptr, .nm_register_func Init, .nm_modname nativeadder, .nm_priv nullptr, .reserved {0}, }; extern C __attribute__((constructor)) void RegisterModule(void) { napi_module_register(demoModule); }napi_get_cb_info把 JS 传进来的两个参数取出来napi_get_value_double转成 C 的 doublenapi_create_double把结果包回 JS 的 number。napi_define_properties把add挂到模块的导出对象上。nm_modname是模块名JS 侧import时用的就是这个名字。JS 侧这样调// 引入 native 模块 import nativeadder from libnativeadder.so; export default { onAddNative() { // 调用 C 侧的 add 函数 const result nativeadder.add(3, 4); console.log(native result: result); } }import的路径是编译产物libnativeadder.so名字要和 C 侧nm_modname对应。nativeadder.add(3, 4)直接调 C 函数返回值是 JS 的 number。这一步跑通说明 full sdk 的native分支和js分支的桥接是完整的。我自己的习惯是每次换 SDK 版本先跑一遍这个 native 加法 demo再跑一遍纯 JS 页面预览。两个都过了才认为环境是干净的。从那以后我每次配新环境都强制走一遍这两步省得写到一半才发现某个分支是残的。希望帮到你。本文还有配套的精品资源点击获取