企业官网建设流程全解析

简介：本资源为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人学习下载。通过该包，读者可获取完整的JS接口调用能力、配套文档与示例工程，用于构建、编译和调试OpenHarmony应用，降低跨设备开发的学习成本，适合具备一定前端或鸿蒙开发基础、希望深入实践OpenHarmony生态的中高级开发者参考使用。

1. 拿到 js-windows-x64 这个包，先搞清楚它到底缺了什么

如果你最近在 Windows 上折腾 OpenHarmony 5.1.0 的 full sdk 公版，大概率会遇到一个很具体的场景：下载完 SDK 包，解压一看，目录里躺着js-windows-x64-5.1.0.107-Release这么一长串名字，但真正跑hvigorw或者用 DevEco 建工程的时候，编译报错、找不到工具链、ace-loader起不来，各种问题全冒出来了。这个包名拆开看信息量很大：js说明它面向的是 ArkTS/JS 应用开发这条线，windows-x64是宿主平台，5.1.0.107-Release是版本和构建类型。它不是一个完整 IDE，也不是设备侧镜像，而是 full sdk 里负责 Windows 主机侧 JS 应用构建的那一块。

很多人第一次接触会误以为 full sdk 就是一个大压缩包解压即用，实际上公版 full sdk 是按组件拆分的，js-windows-x64只是其中面向应用编译的一支。它解决的核心问题是：让你在 Windows 机器上，不依赖 Mac 或 Linux，就能完成 ArkTS 工程的编译、打包、签名前的产物生成。适合谁？适合做 HarmonyOS NEXT 应用开发、需要在 CI 上跑 Windows 构建节点、或者本地想脱离 IDE 用命令行验证编译链路的从业者。这一章先把边界划清楚，后面才好动手。

2. 拆开这个包：目录结构、工具链和它依赖的宿主环境

2.1 解压后你会看到什么，每个目录干什么

把js-windows-x64-5.1.0.107-Release解压到一个没有中文、没有空格的路径下，比如D:\ohsdk\js-windows-x64。常见做法是它内部会有类似ets、toolchains、build-tools、previewer这几类目录（不同构建批次命名会有差异，以你实际解压结果为准）。ets目录放的是 ArkTS 编译相关的 loader 和 API 声明，toolchains里是hvigor、ohpm这类命令行工具，build-tools里是打包和资源处理的可执行文件。

这里有个血泪经验：不要把这个包直接丢进 DevEco Studio 自带的 sdk 目录里覆盖。IDE 自带的 sdk 和公版 full sdk 的目录约定不完全一样，覆盖之后 IDE 可能识别不到，反而把原本能用的环境搞坏。正确做法是单独放一个目录，通过环境变量或工程级配置指向它。

2.2 环境变量怎么配，配错一个就全盘报错

Windows 上跑这套工具链，核心是三个变量：JAVA_HOME、NODE_HOME、以及指向 sdk 根目录的变量（常见命名是OHOS_SDK_HOME或HOS_SDK_HOME，看你用的工具版本约定）。下面是一段 PowerShell 里设置当前会话变量的写法，方便你先验证再决定要不要写进系统变量：

# 临时设置，只对当前 PowerShell 会话生效，验证用 $env:JAVA_HOME = "D:\tools\jdk17" $env:NODE_HOME = "D:\tools\node18" $env:OHOS_SDK_HOME = "D:\ohsdk\js-windows-x64" # 把工具链加进 PATH，注意顺序：sdk 的 toolchains 要在前面 $env:Path = "$env:OHOS_SDK_HOME\toolchains;$env:JAVA_HOME\bin;$env:NODE_HOME;$env:Path" # 验证 java 和 node 能不能被找到 java -version node -v

逻辑说明：JAVA_HOME指向 JDK 17（OpenHarmony 5.x 这条线对 JDK 版本敏感，JDK 8 或 21 都可能出问题），NODE_HOME指向 Node 18 系列。PATH 里把 sdk 的toolchains放前面，是为了让hvigorw、ohpm优先用你这份公版 sdk 里的，而不是系统里其他版本。参数上唯一要改的就是三个路径，改成你自己机器上的实际位置。

2.3 用 hvigorw 跑一次最小构建，确认链路通了

环境配好之后，别急着建大工程，先拿一个最小工程验证。假设你已经有一个 ArkTS 空工程，在工程根目录执行：

# Windows 下用 hvigorw.bat，Git Bash 里可以直接用 hvigorw ./hvigorw.bat --version # 清理并构建 debug 产物 ./hvigorw.bat clean --no-daemon ./hvigorw.bat assembleHap --mode module -p product=default --no-daemon

逻辑说明：--version先确认 hvigor 能被调起来，这一步失败基本就是 PATH 或 JAVA_HOME 的问题。clean加--no-daemon是为了避免守护进程缓存了旧的 sdk 路径，排查阶段建议都带上。assembleHap是产出 HAP 包的核心任务，-p product=default指定产品维度。如果这一步报Cannot find module 'xxx'，八成是ets目录没被正确识别，回去检查OHOS_SDK_HOME是否指向了解压后的根目录而不是它的上一层。

3. 把公版 sdk 接进工程：配置项、路径映射和版本对齐

3.1 工程级配置里怎么指向这份 sdk

命令行能跑通不代表工程配置对了。ArkTS 工程里通常有一个build-profile.json5和hvigorfile.ts，sdk 路径的指定方式在不同工具版本里不一样。常见做法是在工程根目录的local.properties里写 sdk 路径：

# local.properties，不要提交到版本库 sdk.dir=D\:\\ohsdk\\js-windows-x64 nodejs.dir=D\:\\tools\\node18

逻辑说明：Windows 路径在 properties 文件里反斜杠要转义，写成双反斜杠或者用正斜杠。sdk.dir指向的就是你解压出来的那份公版 sdk 根目录。这个文件是本地配置，团队协作时每个人路径不同，所以一般加进.gitignore。

3.2 版本号 5.1.0.107 意味着什么，能不能混用

包名里的5.1.0.107是构建号，Release表示这是发布构建而非调试构建。这里有个容易翻车的点：公版 sdk 的构建号和 IDE 版本、命令行工具版本之间存在对应关系。你拿 5.1.0.107 的 sdk 去配一个明显更老或更新的 hvigor，可能出现 API 声明对不上、编译期报找不到某个@ohos.xxx模块。

我一般会这样做对齐检查：先看工程oh-package.json5里声明的compileSdkVersion和compatibleSdkVersion，确保它们和这份 sdk 的主版本 5.1.0 一致。如果工程是从别处拷来的，版本号写着 5.0.x，那要么改工程配置，要么换对应版本的 sdk，别硬混。

3.3 用一张表把关键路径和对应关系理清

排查路径问题时，对着下面这张表逐项核对，比盲目试错快得多：

这张表里的值都要换成你机器上的实际路径和工程实际声明。表格的作用是让你在报错时有个对照清单，而不是凭感觉改。

4. 避坑与排查：这几类报错我踩过不止一次

4.1 现象：hvigorw 报 “JAVA_HOME is not set” 但明明设了

原因通常有两个：一是设的是用户变量但当前终端是管理员权限开的，读的是另一套环境；二是路径末尾多了个反斜杠或引号，工具解析时拼出了非法路径。解决方式是先在当前终端echo %JAVA_HOME%（cmd）或$env:JAVA_HOME（PowerShell）确认实际值，去掉末尾斜杠，重启终端再试。别在系统变量和用户变量里同时设不同的值，那是自找麻烦。

4.2 现象：assembleHap 卡在 “Resolving dependencies” 很久然后失败

原因基本是 ohpm 仓库访问不通或代理配置残留。检查工程根目录有没有.ohpmrc，里面如果写了指向某个内网仓库的 registry，而你现在不在那个网络里，就会一直超时。解决方式是临时把 registry 指回默认源，或者确认你的网络能访问依赖仓库。这一步和 sdk 本身无关，但报错信息会误导你以为 sdk 坏了。

4.3 现象：编译通过但 previewer 起不来，白屏

原因多半是 previewer 依赖的图形库或路径里有中文。js-windows-x64里的 previewer 对路径非常敏感，解压路径带中文、带空格、带特殊符号都可能让它静默失败。解决方式是把 sdk 挪到纯英文短路径下，比如D:\ohsdk，然后重新配sdk.dir。这个坑很玄学，报错日志里往往什么都不说，只能靠换路径验证。

4.4 现象：换了一台机器，同样的工程报 “module not found”

原因是local.properties没跟着走，或者新机器上的 sdk 版本和旧机器不一致。解决方式是确认新机器解压的是同一个构建号5.1.0.107，并且local.properties里的路径改成了新机器的实际路径。团队里最好把 sdk 版本号写进工程文档，而不是靠每个人自己记。

4.5 现象：Release 构建产物签名失败

原因是用 Release 构建时签名配置和 Debug 不同，build-profile.json5里的 signingConfigs 如果还是 Debug 的证书，就会失败。解决方式是单独配一套 Release 签名，或者在验证阶段先用 Debug 模式确认编译链路，签名问题单独处理。别把编译失败和签名失败混为一谈，它们的排查路径完全不同。

5. 进阶：把这份 sdk 用进 CI，以及一个验证构建产物的小技巧

前面讲的都是本地手动跑，真正体现价值的是把它接进 CI。Windows 构建节点上，你可以把 sdk 解压到一个固定路径，用脚本设置环境变量，然后跑hvigorw assembleHap。关键点是：CI 上不要依赖系统级环境变量，全部在构建脚本里显式设置，这样换节点不会翻车。下面是一段 CI 里常见的 PowerShell 片段：

# CI 构建脚本片段，所有路径显式指定，不依赖系统变量 $ErrorActionPreference = "Stop" $env:JAVA_HOME = "C:\ci\tools\jdk17" $env:NODE_HOME = "C:\ci\tools\node18" $env:OHOS_SDK_HOME = "C:\ci\sdk\js-windows-x64" $env:Path = "$env:OHOS_SDK_HOME\toolchains;$env:JAVA_HOME\bin;$env:NODE_HOME;$env:Path" # 先打印版本，构建日志里留痕，方便回溯 & "$env:OHOS_SDK_HOME\toolchains\hvigorw.bat" --version # 执行构建，失败即中断 & "$env:OHOS_SDK_HOME\toolchains\hvigorw.bat" clean --no-daemon & "$env:OHOS_SDK_HOME\toolchains\hvigorw.bat" assembleHap --mode module -p product=default --no-daemon

逻辑说明：$ErrorActionPreference = "Stop"让任何一步失败都立即中断，避免 CI 假成功。显式设置三个变量和 PATH，保证构建环境可复现。先跑--version是为了在日志里留下 sdk 和工具版本，出问题时能快速定位是哪次构建换了版本。参数上--no-daemon在 CI 里建议保留，守护进程在一次性容器里没有意义，还可能残留状态。

再给一个验证产物的小技巧：构建出来的 HAP 其实是个 zip，你可以直接改后缀解压，看里面的ets编译产物和资源有没有打进去。这比只看“构建成功”四个字靠谱得多。我一般会检查解压后的modules.abc是否存在、resources.index大小是否正常，如果resources.index只有几百字节，多半是资源没打进去，得回去看资源目录配置。

最后说个我自己的习惯：每次换 sdk 构建号，我都会先在一个最小空工程上跑一遍完整链路，确认没问题再往正式工程上套。这个习惯帮我省过好几次“以为是代码问题、其实是 sdk 换了”的冤枉时间。公版 sdk 的构建号更新不算频繁，但每次更新都可能动到工具链细节，先用最小工程探路，比在复杂工程里大海捞针强。希望帮到你。

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