1. 为什么 DevEco Studio 里找不到 full_sdkOpenHarmony 高权限 API 开发场景拆解如果你正在用 DevEco Studio 开发 OpenHarmony 应用大概率会遇到一个很别扭的情况明明装好了 IDE新建工程也能跑但一旦代码里用到系统应用级别的高权限 API编译立刻报错提示找不到符号或者接口不存在。这不是你代码写错了而是你用的 SDK 类型不对。OpenHarmony 的 SDK 分成两类这个区分非常关键。public-SDK 是给普通应用开发者用的工具包它会跟随 DevEco Studio 一起下载开箱即用但里面不包含系统应用所需要的高权限 API。full-SDK 则是提供给 OEM 厂商和系统应用开发者使用的工具包它包含了那些高权限 API但它不会随 DevEco Studio 自动下载需要你自己从 OpenHarmony 源码编译产出或者拿到对应版本的完整包后手动替换。所以「鸿蒙 full_sdk 使用指南」这件事的核心不是教你怎么点下一步而是搞清楚三件事full_sdk 从哪来、放到哪个目录、怎么让 DevEco Studio 和 hvigor 构建系统真正认到它。很多人卡在最后一步文件明明复制进去了编译还是走 public-SDK原因就是路径层级或者 runtimeOS 参数没对上。这篇文章面向的是已经在做 OpenHarmony 开发、需要调用系统级能力的开发者。我会按真实操作顺序走一遍先说明 full_sdk 的获取方式再讲目录结构和替换动作然后给出可复制的路径配置片段和 hvigor 验证命令最后把几个高频报错逐个拆开。你跟着做完应该能在本地跑通第一个依赖 full_sdk 的工程。需要提前说清楚一点full_sdk 的编译依赖 OpenHarmony 源码和 Linux 编译环境如果你只是想快速拿到包也可以直接使用官方或社区提供的对应版本 SDK 包跳过编译环节。两条路我都会提到你按自己的条件选。另外SDK 版本和 DevEco Studio 版本、runtimeOS 三者必须对齐。我见过太多人拿着 3.2 的 full_sdk 去配 4.0 的工程或者 runtimeOS 写 HarmonyOS 却放了 OpenHarmony 的包结果就是各种莫名其妙的报错。版本对齐这件事后面每个环节我都会提醒。2. full_sdk 获取与 TaoToken 前置准备编译产出与 API 接入环境先说 full_sdk 的两种获取路径你根据自己情况选。第一种是从 OpenHarmony 源码编译产出。这条路适合需要特定版本、或者要做定制裁剪的团队。基本流程是拉取 OpenHarmony 源码在 Linux 环境下执行编译命令产物在 out/sdk/packages/ohos-sdk/ 目录下。编译命令大致是这样./build.sh --product-name ohos-sdk编译过程对系统依赖比较敏感常见的缺库报错集中在图形相关的 dev 包上。一次性把常用的装上能省很多来回apt install libxcursor-dev libxrandr-dev libxinerama-dev如果编译中途单独报某个库缺失就按提示补装对应的 dev 包比如 libxcursor-dev、libxrandr-dev、libxinerama-dev 这几个是最常缺的。编译成功后把 out/sdk/packages/ohos-sdk/ 目录下的文件导出这就是你的 full_sdk 原始产物。第二种是直接使用对应版本的 SDK 包。如果你不做定制只是要那套高权限 API用现成的包更省事。关键是对上版本号OpenHarmony 3.2 Release、4.0 Release 这些版本都有对应的 SDK 包下载后解压即可目录结构和编译产出是一致的。这里插一个实际开发中会遇到的配套问题当你的 OpenHarmony 工程需要接入大模型能力比如做 AI 对话、代码辅助或者 Agent 类功能时SDK 本身不提供模型服务你需要一个兼容 OpenAI 接口协议的 API 网关。我这边常用的是 TaoToken它的接口地址是 https://taotoken.net/api兼容标准 chat completions 格式在 OpenHarmony 的网络请求里直接按普通 HTTP 接口调用就行不需要额外适配层。TaoToken 的 API Key 在控制台创建地址是 https://taotoken.net/api-keys创建后复制出来在工程里通过环境变量或者配置文件注入不要硬编码进源码。模型 ID 按你实际要用的填比如做代码补全和长文本理解选对应能力的模型即可。接入文档在 https://taotoken.net/doc里面有完整的请求示例和参数说明。如果你后续要做长期的编码辅助或者 Agent 工作流可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan它更适合持续性的开发场景。想先验证模型对话效果可以直接在 https://taotoken.net/chat 里试。回到 full_sdk。无论你走编译还是用现成包拿到之后先别急着往 DevEco Studio 里塞先确认三件事SDK 版本号、对应的 API 版本、以及你的工程 runtimeOS 是 OpenHarmony 还是 HarmonyOS。这三个对不上后面全是坑。3. full_sdk 目录替换与可复制配置片段ets-loader 依赖与 runtimeOS 对齐拿到 full_sdk 后核心动作是替换 DevEco Studio 使用的 SDK 目录。DevEco Studio 的 SDK 一般放在类似这样的路径下Windows 和 macOS 略有差异以你本机实际为准DevEco Studio 安装目录/sdk/版本号/或者你在设置里自定义过 SDK 路径那就去那个路径找。目录里通常有 ets、js、native、toolchains 等子目录。full_sdk 解压后同样会得到 ets 文件夹等结构你要做的是把 full_sdk 里的对应目录复制过去覆盖原本 public-SDK 的内容。复制完成后有一个步骤绝对不能漏进入 build-tools/ets-loader 目录安装 node_modules 依赖。因为 ets-loader 是编译 ets 代码的关键工具它依赖一堆 npm 包public-SDK 里可能已经装好了但你替换成 full_sdk 后这个目录的依赖需要重新装。在 ets-loader 目录下打开 cmd 或 PowerShellmacOS/Linux 用终端执行npm install这一步会下载 node_modules 依赖包。如果网络慢可以配国内镜像源。装完之后ets-loader 才具备编译 full_sdk 工程的能力。接下来是最容易出错的地方build-profile.json5 里的 runtimeOS 参数。这个参数必须和你的 SDK 目录类型对应。如果你用的是 OpenHarmony 的 full_sdkruntimeOS 要写 OpenHarmony如果你用的是 HarmonyOS 的 SDK就写 HarmonyOS。写错了构建系统会去找不匹配的 SDK直接报错。一个典型的 build-profile.json5 配置片段长这样{ app: { products: [ { name: default, signingConfig: default, compileSdkVersion: 10, compatibleSdkVersion: 10, runtimeOS: OpenHarmony } ] }, modules: [ { name: entry, srcPath: ./entry, targets: [ { name: default, applyToProducts: [default] } ] } ] }注意 compileSdkVersion 和 compatibleSdkVersion 要和你实际放的 SDK 版本对应。比如你放的是 API 10 的 full_sdk这里就写 10。版本号对不上编译一样会失败。如果你在工程里通过配置文件管理 API 接入信息可以单独放一个 config 文件比如{ apiBaseUrl: https://taotoken.net/api, apiKey: 你的_API_KEY, modelId: 你的模型ID }这个文件不要提交到公开仓库用 .gitignore 排除掉。API Key 从 https://taotoken.net/api-keys 创建获取模型 ID 按你实际使用的填。这样你的 OpenHarmony 工程既能用 full_sdk 的高权限 API又能通过标准 HTTP 接口调用模型能力两件事互不干扰。配置改完后建议清理一次构建缓存再重新编译避免旧的 public-SDK 缓存干扰。DevEco Studio 里可以走 Build Clean Project命令行下可以删掉 build 目录和 .hvigor 缓存目录。4. hvigor 构建验证与成功结果确认环境变量检查清单配置改完怎么确认 full_sdk 真的生效了最直接的办法是用 hvigor 命令行构建一次看它实际用的是哪个 SDK。在工程根目录执行hvigorw assembleHap --mode module -p productdefault或者用 DevEco Studio 自带的 hvigor 包装器./hvigorw clean ./hvigorw assembleHap构建过程中如果 full_sdk 配置正确你会看到编译顺利通过产物 hap 生成在 entry/build/default/outputs/default/ 目录下。如果 SDK 没对上构建会在编译阶段报错提示找不到某些 API 或者 SDK 路径无效。想更明确地确认当前用的是哪个 SDK可以检查环境变量和 IDE 配置。下面是一份环境变量检查清单逐项对一遍检查项期望值说明DEVECO_SDK_HOME指向你的 SDK 根目录DevEco Studio 读取 SDK 的入口SDK 目录下 ets 版本与工程 compileSdkVersion 一致版本错位会编译失败build-profile.json5 runtimeOSOpenHarmony 或 HarmonyOS必须与 SDK 类型对应ets-loader/node_modules存在且完整缺失会导致 ets 编译失败hvigor 版本与工程 hvigor-config.json5 匹配版本不匹配会构建异常DEVECO_SDK_HOME 这个环境变量在 Windows 上可以通过系统环境变量设置macOS/Linux 在 shell 配置文件里 export。设置后重启 DevEco Studio 让它生效。验证成功的标志有几个hvigor 构建输出 BUILD SUCCESSFUL工程里原本报错的高权限 API 不再飘红生成的 hap 能正常安装到设备或模拟器。到这一步full_sdk 就算真正跑通了。如果你在工程里同时接了模型 API可以写一个简单的网络请求测试确认能拿到返回。用 OpenHarmony 的 http 模块发一个 POST 请求到 https://taotoken.net/api 的 chat completions 接口带上 API Key 和模型 ID看返回是否正常。这一步能同时验证网络权限配置和 API 接入是否正确。构建验证通过后建议把这次成功的配置记录下来尤其是 SDK 版本、runtimeOS、hvigor 版本这三个组合。下次换机器或者升级版本时直接对照能省掉大量排查时间。5. full_sdk 安装高频报错排查401、local proxy failed 与 reading choices 对照这一节把几个真实高频报错逐个拆开。这些报错我在不同项目里都遇到过按现象对号入座即可。报错一编译时提示找不到高权限 API 符号现象是代码里调用的系统级接口飘红编译报 undefined symbol 或接口不存在。原因基本是 SDK 没替换成功或者替换了但 runtimeOS 写错构建系统还在用 public-SDK。排查顺序先确认 SDK 目录下 ets 里的 API 声明文件是否包含你要用的接口再检查 build-profile.json5 的 runtimeOS 是否和 SDK 类型一致最后清理缓存重新构建。三步走完基本能定位。报错二ets-loader 编译报错提示模块找不到这通常是替换 full_sdk 后没在 build-tools/ets-loader 目录执行 npm install。ets-loader 的 node_modules 依赖缺失编译 ets 代码时就会报模块解析失败。解决办法就是进到那个目录重新 npm install装完再构建。如果 npm install 本身报错检查网络和镜像源配置。报错三401 Unauthorized这个报错出现在你调用模型 API 的时候不是 SDK 本身的问题。401 表示 API Key 无效或没带上。检查你的请求头里 Authorization 字段格式是否正确通常是 Bearer 加空格加 Key。Key 从 https://taotoken.net/api-keys 创建确认没有多余空格或换行。如果 Key 是对的还报 401检查是不是用了过期的 Key 或者账户状态异常。报错四local proxy failed这个报错一般出现在网络请求环节表示请求没能正常发出去。常见原因是工程没申请网络权限或者请求地址配置有误。OpenHarmony 工程需要在 module.json5 里声明 ohos.permission.INTERNET 权限。另外确认你的请求地址是 https://taotoken.net/api 这样的完整地址没有拼错。如果是在模拟器里跑确认模拟器网络正常。报错五reading choices 相关报错这个报错出现在解析模型返回结果时提示读取 choices 字段失败。原因通常是返回结构和你解析的字段不匹配或者请求本身失败了返回了错误结构。先打印完整返回内容看结构确认 choices 数组存在。如果返回的是错误信息先解决错误再解析 choices。另外确认你用的模型 ID 是有效的模型 ID 不对可能返回非预期结构。报错六OAuth 相关报错如果你在接入过程中看到 OAuth 字样通常是认证方式用错了。TaoToken 的 API 接入用的是 API Key 方式不是 OAuth 流程。确认你走的是 API Key 认证请求头带 Authorization。不要混用其他认证方式。排查这些报错有个通用思路先分清是 SDK 层面的问题还是 API 调用层面的问题。SDK 问题看编译日志和目录结构API 问题看请求和返回。两边分开查效率高很多。6. 从 full_sdk 到模型接入OpenHarmony 工程落地与后续路径把 full_sdk 配好只是第一步真正让工程跑起来还要把 SDK 能力和你的业务逻辑接上。如果你的 OpenHarmony 应用需要 AI 能力比如智能问答、代码辅助、内容生成那模型接入就是绕不开的一环。接入方式前面提过用兼容 OpenAI 协议的 API 网关最省事。TaoToken 的接口地址是 https://taotoken.net/api在 OpenHarmony 的 http 模块里按标准 POST 请求调用即可。请求体里带上 model、messages 这些字段请求头带 Authorization。返回结构是标准的 choices 数组解析方式和你在其他平台用 OpenAI 接口一样。API Key 管理上建议在工程里做一层封装把 Key 和模型 ID 放在单独的配置模块不要散落在各处。这样换 Key 或者换模型时只改一个地方。Key 从 https://taotoken.net/api-keys 创建接入文档在 https://taotoken.net/doc 有完整示例。如果你做的是长期编码辅助或者 Agent 类工作流可以看下 Coding Plan地址是 https://taotoken.net/coding-plan它针对持续性开发场景做了优化。想先快速验证模型对话效果直接在 https://taotoken.net/chat 里试就行不用写代码。回到工程本身full_sdk 跑通后建议做几件事巩固环境把成功的 SDK 版本、runtimeOS、hvigor 版本组合记录下来把 ets-loader 的 npm install 步骤写进团队的环境搭建文档把 build-profile.json5 的关键配置做成模板。这些动作能让团队里其他人少踩坑。最后提醒一个实际经验SDK 版本升级时full_sdk 要跟着换runtimeOS 和 compileSdkVersion 也要同步改。三者是一个整体动一个就要检查另外两个。我见过升级 DevEco Studio 后忘了换 full_sdk结果编译报一堆找不到接口的错排查半天才发现是版本没对齐。环境搭好之后把精力放回业务代码上。full_sdk 提供的高权限 API 能让你做很多 public-SDK 做不了的事模型接入又能补上 AI 能力这两块配合起来OpenHarmony 工程的可玩性会高很多。