企业官网建设流程全解析

简介：本资源为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.107，Release 构建，平台是 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和native；windows是宿主平台，不是目标设备平台，目标设备仍然是 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 目录结构里哪些是必须的

解压之后，根目录下一般能看到这么几个东西：

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 --version

hvigorw.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.107，Device 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 class="container"> <text class="title">{{ count }}</text> <button class="btn" onclick="onAdd">加一</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 }}是数据绑定，onclick="onAdd"把按钮点击绑到函数上。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 的 double，napi_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 页面预览。两个都过了，才认为环境是干净的。从那以后我每次配新环境都强制走一遍这两步，省得写到一半才发现某个分支是残的。希望帮到你。

本文还有配套的精品资源，点击获取