1. 為什么 DevEco Studio 里找不到 full_sdkOpenHarmony 高權(quán)限 API 開發(fā)場(chǎng)景拆解如果你正在用 DevEco Studio 開發(fā) OpenHarmony 應(yīng)用大概率會(huì)遇到一個(gè)很別扭的情況明明裝好了 IDE新建工程也能跑但一旦代碼里用到系統(tǒng)應(yīng)用級(jí)別的高權(quán)限 API編譯立刻報(bào)錯(cuò)提示找不到符號(hào)或者接口不存在。這不是你代碼寫錯(cuò)了而是你用的 SDK 類型不對(duì)。OpenHarmony 的 SDK 分成兩類這個(gè)區(qū)分非常關(guān)鍵。public-SDK 是給普通應(yīng)用開發(fā)者用的工具包它會(huì)跟隨 DevEco Studio 一起下載開箱即用但里面不包含系統(tǒng)應(yīng)用所需要的高權(quán)限 API。full-SDK 則是提供給 OEM 廠商和系統(tǒng)應(yīng)用開發(fā)者使用的工具包它包含了那些高權(quán)限 API但它不會(huì)隨 DevEco Studio 自動(dòng)下載需要你自己從 OpenHarmony 源碼編譯產(chǎn)出或者拿到對(duì)應(yīng)版本的完整包后手動(dòng)替換。所以「鴻蒙 full_sdk 使用指南」這件事的核心不是教你怎么點(diǎn)下一步而是搞清楚三件事full_sdk 從哪來、放到哪個(gè)目錄、怎么讓 DevEco Studio 和 hvigor 構(gòu)建系統(tǒng)真正認(rèn)到它。很多人卡在最后一步文件明明復(fù)制進(jìn)去了編譯還是走 public-SDK原因就是路徑層級(jí)或者 runtimeOS 參數(shù)沒對(duì)上。這篇文章面向的是已經(jīng)在做 OpenHarmony 開發(fā)、需要調(diào)用系統(tǒng)級(jí)能力的開發(fā)者。我會(huì)按真實(shí)操作順序走一遍先說明 full_sdk 的獲取方式再講目錄結(jié)構(gòu)和替換動(dòng)作然后給出可復(fù)制的路徑配置片段和 hvigor 驗(yàn)證命令最后把幾個(gè)高頻報(bào)錯(cuò)逐個(gè)拆開。你跟著做完應(yīng)該能在本地跑通第一個(gè)依賴 full_sdk 的工程。需要提前說清楚一點(diǎn)full_sdk 的編譯依賴 OpenHarmony 源碼和 Linux 編譯環(huán)境如果你只是想快速拿到包也可以直接使用官方或社區(qū)提供的對(duì)應(yīng)版本 SDK 包跳過編譯環(huán)節(jié)。兩條路我都會(huì)提到你按自己的條件選。另外SDK 版本和 DevEco Studio 版本、runtimeOS 三者必須對(duì)齊。我見過太多人拿著 3.2 的 full_sdk 去配 4.0 的工程或者 runtimeOS 寫 HarmonyOS 卻放了 OpenHarmony 的包結(jié)果就是各種莫名其妙的報(bào)錯(cuò)。版本對(duì)齊這件事后面每個(gè)環(huán)節(jié)我都會(huì)提醒。2. full_sdk 獲取與 TaoToken 前置準(zhǔn)備編譯產(chǎn)出與 API 接入環(huán)境先說 full_sdk 的兩種獲取路徑你根據(jù)自己情況選。第一種是從 OpenHarmony 源碼編譯產(chǎn)出。這條路適合需要特定版本、或者要做定制裁剪的團(tuán)隊(duì)?；玖鞒淌抢?OpenHarmony 源碼在 Linux 環(huán)境下執(zhí)行編譯命令產(chǎn)物在 out/sdk/packages/ohos-sdk/ 目錄下。編譯命令大致是這樣./build.sh --product-name ohos-sdk編譯過程對(duì)系統(tǒng)依賴比較敏感常見的缺庫(kù)報(bào)錯(cuò)集中在圖形相關(guān)的 dev 包上。一次性把常用的裝上能省很多來回apt install libxcursor-dev libxrandr-dev libxinerama-dev如果編譯中途單獨(dú)報(bào)某個(gè)庫(kù)缺失就按提示補(bǔ)裝對(duì)應(yīng)的 dev 包比如 libxcursor-dev、libxrandr-dev、libxinerama-dev 這幾個(gè)是最常缺的。編譯成功后把 out/sdk/packages/ohos-sdk/ 目錄下的文件導(dǎo)出這就是你的 full_sdk 原始產(chǎn)物。第二種是直接使用對(duì)應(yīng)版本的 SDK 包。如果你不做定制只是要那套高權(quán)限 API用現(xiàn)成的包更省事。關(guān)鍵是對(duì)上版本號(hào)OpenHarmony 3.2 Release、4.0 Release 這些版本都有對(duì)應(yīng)的 SDK 包下載后解壓即可目錄結(jié)構(gòu)和編譯產(chǎn)出是一致的。這里插一個(gè)實(shí)際開發(fā)中會(huì)遇到的配套問題當(dāng)你的 OpenHarmony 工程需要接入大模型能力比如做 AI 對(duì)話、代碼輔助或者 Agent 類功能時(shí)SDK 本身不提供模型服務(wù)你需要一個(gè)兼容 OpenAI 接口協(xié)議的 API 網(wǎng)關(guān)。我這邊常用的是 TaoToken它的接口地址是 https://taotoken.net/api兼容標(biāo)準(zhǔn) chat completions 格式在 OpenHarmony 的網(wǎng)絡(luò)請(qǐng)求里直接按普通 HTTP 接口調(diào)用就行不需要額外適配層。TaoToken 的 API Key 在控制臺(tái)創(chuàng)建地址是 https://taotoken.net/api-keys創(chuàng)建后復(fù)制出來在工程里通過環(huán)境變量或者配置文件注入不要硬編碼進(jìn)源碼。模型 ID 按你實(shí)際要用的填比如做代碼補(bǔ)全和長(zhǎng)文本理解選對(duì)應(yīng)能力的模型即可。接入文檔在 https://taotoken.net/doc里面有完整的請(qǐng)求示例和參數(shù)說明。如果你后續(xù)要做長(zhǎng)期的編碼輔助或者 Agent 工作流可以了解下 Coding Plan地址是 https://taotoken.net/coding-plan它更適合持續(xù)性的開發(fā)場(chǎng)景。想先驗(yàn)證模型對(duì)話效果可以直接在 https://taotoken.net/chat 里試?；氐?full_sdk。無論你走編譯還是用現(xiàn)成包拿到之后先別急著往 DevEco Studio 里塞先確認(rèn)三件事SDK 版本號(hào)、對(duì)應(yīng)的 API 版本、以及你的工程 runtimeOS 是 OpenHarmony 還是 HarmonyOS。這三個(gè)對(duì)不上后面全是坑。3. full_sdk 目錄替換與可復(fù)制配置片段ets-loader 依賴與 runtimeOS 對(duì)齊拿到 full_sdk 后核心動(dòng)作是替換 DevEco Studio 使用的 SDK 目錄。DevEco Studio 的 SDK 一般放在類似這樣的路徑下Windows 和 macOS 略有差異以你本機(jī)實(shí)際為準(zhǔn)DevEco Studio 安裝目錄/sdk/版本號(hào)/或者你在設(shè)置里自定義過 SDK 路徑那就去那個(gè)路徑找。目錄里通常有 ets、js、native、toolchains 等子目錄。full_sdk 解壓后同樣會(huì)得到 ets 文件夾等結(jié)構(gòu)你要做的是把 full_sdk 里的對(duì)應(yīng)目錄復(fù)制過去覆蓋原本 public-SDK 的內(nèi)容。復(fù)制完成后有一個(gè)步驟絕對(duì)不能漏進(jìn)入 build-tools/ets-loader 目錄安裝 node_modules 依賴。因?yàn)?ets-loader 是編譯 ets 代碼的關(guān)鍵工具它依賴一堆 npm 包public-SDK 里可能已經(jīng)裝好了但你替換成 full_sdk 后這個(gè)目錄的依賴需要重新裝。在 ets-loader 目錄下打開 cmd 或 PowerShellmacOS/Linux 用終端執(zhí)行npm install這一步會(huì)下載 node_modules 依賴包。如果網(wǎng)絡(luò)慢可以配國(guó)內(nèi)鏡像源。裝完之后ets-loader 才具備編譯 full_sdk 工程的能力。接下來是最容易出錯(cuò)的地方build-profile.json5 里的 runtimeOS 參數(shù)。這個(gè)參數(shù)必須和你的 SDK 目錄類型對(duì)應(yīng)。如果你用的是 OpenHarmony 的 full_sdkruntimeOS 要寫 OpenHarmony如果你用的是 HarmonyOS 的 SDK就寫 HarmonyOS。寫錯(cuò)了構(gòu)建系統(tǒng)會(huì)去找不匹配的 SDK直接報(bào)錯(cuò)。一個(gè)典型的 build-profile.json5 配置片段長(zhǎng)這樣{ app: { products: [ { name: default, signingConfig: default, compileSdkVersion: 10, compatibleSdkVersion: 10, runtimeOS: OpenHarmony } ] }, modules: [ { name: entry, srcPath: ./entry, targets: [ { name: default, applyToProducts: [default] } ] } ] }注意 compileSdkVersion 和 compatibleSdkVersion 要和你實(shí)際放的 SDK 版本對(duì)應(yīng)。比如你放的是 API 10 的 full_sdk這里就寫 10。版本號(hào)對(duì)不上編譯一樣會(huì)失敗。如果你在工程里通過配置文件管理 API 接入信息可以單獨(dú)放一個(gè) config 文件比如{ apiBaseUrl: https://taotoken.net/api, apiKey: 你的_API_KEY, modelId: 你的模型ID }這個(gè)文件不要提交到公開倉(cāng)庫(kù)用 .gitignore 排除掉。API Key 從 https://taotoken.net/api-keys 創(chuàng)建獲取模型 ID 按你實(shí)際使用的填。這樣你的 OpenHarmony 工程既能用 full_sdk 的高權(quán)限 API又能通過標(biāo)準(zhǔn) HTTP 接口調(diào)用模型能力兩件事互不干擾。配置改完后建議清理一次構(gòu)建緩存再重新編譯避免舊的 public-SDK 緩存干擾。DevEco Studio 里可以走 Build Clean Project命令行下可以刪掉 build 目錄和 .hvigor 緩存目錄。4. hvigor 構(gòu)建驗(yàn)證與成功結(jié)果確認(rèn)環(huán)境變量檢查清單配置改完怎么確認(rèn) full_sdk 真的生效了最直接的辦法是用 hvigor 命令行構(gòu)建一次看它實(shí)際用的是哪個(gè) SDK。在工程根目錄執(zhí)行hvigorw assembleHap --mode module -p productdefault或者用 DevEco Studio 自帶的 hvigor 包裝器./hvigorw clean ./hvigorw assembleHap構(gòu)建過程中如果 full_sdk 配置正確你會(huì)看到編譯順利通過產(chǎn)物 hap 生成在 entry/build/default/outputs/default/ 目錄下。如果 SDK 沒對(duì)上構(gòu)建會(huì)在編譯階段報(bào)錯(cuò)提示找不到某些 API 或者 SDK 路徑無效。想更明確地確認(rèn)當(dāng)前用的是哪個(gè) SDK可以檢查環(huán)境變量和 IDE 配置。下面是一份環(huán)境變量檢查清單逐項(xiàng)對(duì)一遍檢查項(xiàng)期望值說明DEVECO_SDK_HOME指向你的 SDK 根目錄DevEco Studio 讀取 SDK 的入口SDK 目錄下 ets 版本與工程 compileSdkVersion 一致版本錯(cuò)位會(huì)編譯失敗build-profile.json5 runtimeOSOpenHarmony 或 HarmonyOS必須與 SDK 類型對(duì)應(yīng)ets-loader/node_modules存在且完整缺失會(huì)導(dǎo)致 ets 編譯失敗hvigor 版本與工程 hvigor-config.json5 匹配版本不匹配會(huì)構(gòu)建異常DEVECO_SDK_HOME 這個(gè)環(huán)境變量在 Windows 上可以通過系統(tǒng)環(huán)境變量設(shè)置macOS/Linux 在 shell 配置文件里 export。設(shè)置后重啟 DevEco Studio 讓它生效。驗(yàn)證成功的標(biāo)志有幾個(gè)hvigor 構(gòu)建輸出 BUILD SUCCESSFUL工程里原本報(bào)錯(cuò)的高權(quán)限 API 不再飄紅生成的 hap 能正常安裝到設(shè)備或模擬器。到這一步full_sdk 就算真正跑通了。如果你在工程里同時(shí)接了模型 API可以寫一個(gè)簡(jiǎn)單的網(wǎng)絡(luò)請(qǐng)求測(cè)試確認(rèn)能拿到返回。用 OpenHarmony 的 http 模塊發(fā)一個(gè) POST 請(qǐng)求到 https://taotoken.net/api 的 chat completions 接口帶上 API Key 和模型 ID看返回是否正常。這一步能同時(shí)驗(yàn)證網(wǎng)絡(luò)權(quán)限配置和 API 接入是否正確。構(gòu)建驗(yàn)證通過后建議把這次成功的配置記錄下來尤其是 SDK 版本、runtimeOS、hvigor 版本這三個(gè)組合。下次換機(jī)器或者升級(jí)版本時(shí)直接對(duì)照能省掉大量排查時(shí)間。5. full_sdk 安裝高頻報(bào)錯(cuò)排查401、local proxy failed 與 reading choices 對(duì)照這一節(jié)把幾個(gè)真實(shí)高頻報(bào)錯(cuò)逐個(gè)拆開。這些報(bào)錯(cuò)我在不同項(xiàng)目里都遇到過按現(xiàn)象對(duì)號(hào)入座即可。報(bào)錯(cuò)一編譯時(shí)提示找不到高權(quán)限 API 符號(hào)現(xiàn)象是代碼里調(diào)用的系統(tǒng)級(jí)接口飄紅編譯報(bào) undefined symbol 或接口不存在。原因基本是 SDK 沒替換成功或者替換了但 runtimeOS 寫錯(cuò)構(gòu)建系統(tǒng)還在用 public-SDK。排查順序先確認(rèn) SDK 目錄下 ets 里的 API 聲明文件是否包含你要用的接口再檢查 build-profile.json5 的 runtimeOS 是否和 SDK 類型一致最后清理緩存重新構(gòu)建。三步走完基本能定位。報(bào)錯(cuò)二ets-loader 編譯報(bào)錯(cuò)提示模塊找不到這通常是替換 full_sdk 后沒在 build-tools/ets-loader 目錄執(zhí)行 npm install。ets-loader 的 node_modules 依賴缺失編譯 ets 代碼時(shí)就會(huì)報(bào)模塊解析失敗。解決辦法就是進(jìn)到那個(gè)目錄重新 npm install裝完再構(gòu)建。如果 npm install 本身報(bào)錯(cuò)檢查網(wǎng)絡(luò)和鏡像源配置。報(bào)錯(cuò)三401 Unauthorized這個(gè)報(bào)錯(cuò)出現(xiàn)在你調(diào)用模型 API 的時(shí)候不是 SDK 本身的問題。401 表示 API Key 無效或沒帶上。檢查你的請(qǐng)求頭里 Authorization 字段格式是否正確通常是 Bearer 加空格加 Key。Key 從 https://taotoken.net/api-keys 創(chuàng)建確認(rèn)沒有多余空格或換行。如果 Key 是對(duì)的還報(bào) 401檢查是不是用了過期的 Key 或者賬戶狀態(tài)異常。報(bào)錯(cuò)四local proxy failed這個(gè)報(bào)錯(cuò)一般出現(xiàn)在網(wǎng)絡(luò)請(qǐng)求環(huán)節(jié)表示請(qǐng)求沒能正常發(fā)出去。常見原因是工程沒申請(qǐng)網(wǎng)絡(luò)權(quán)限或者請(qǐng)求地址配置有誤。OpenHarmony 工程需要在 module.json5 里聲明 ohos.permission.INTERNET 權(quán)限。另外確認(rèn)你的請(qǐng)求地址是 https://taotoken.net/api 這樣的完整地址沒有拼錯(cuò)。如果是在模擬器里跑確認(rèn)模擬器網(wǎng)絡(luò)正常。報(bào)錯(cuò)五reading choices 相關(guān)報(bào)錯(cuò)這個(gè)報(bào)錯(cuò)出現(xiàn)在解析模型返回結(jié)果時(shí)提示讀取 choices 字段失敗。原因通常是返回結(jié)構(gòu)和你解析的字段不匹配或者請(qǐng)求本身失敗了返回了錯(cuò)誤結(jié)構(gòu)。先打印完整返回內(nèi)容看結(jié)構(gòu)確認(rèn) choices 數(shù)組存在。如果返回的是錯(cuò)誤信息先解決錯(cuò)誤再解析 choices。另外確認(rèn)你用的模型 ID 是有效的模型 ID 不對(duì)可能返回非預(yù)期結(jié)構(gòu)。報(bào)錯(cuò)六OAuth 相關(guān)報(bào)錯(cuò)如果你在接入過程中看到 OAuth 字樣通常是認(rèn)證方式用錯(cuò)了。TaoToken 的 API 接入用的是 API Key 方式不是 OAuth 流程。確認(rèn)你走的是 API Key 認(rèn)證請(qǐng)求頭帶 Authorization。不要混用其他認(rèn)證方式。排查這些報(bào)錯(cuò)有個(gè)通用思路先分清是 SDK 層面的問題還是 API 調(diào)用層面的問題。SDK 問題看編譯日志和目錄結(jié)構(gòu)API 問題看請(qǐng)求和返回。兩邊分開查效率高很多。6. 從 full_sdk 到模型接入OpenHarmony 工程落地與后續(xù)路徑把 full_sdk 配好只是第一步真正讓工程跑起來還要把 SDK 能力和你的業(yè)務(wù)邏輯接上。如果你的 OpenHarmony 應(yīng)用需要 AI 能力比如智能問答、代碼輔助、內(nèi)容生成那模型接入就是繞不開的一環(huán)。接入方式前面提過用兼容 OpenAI 協(xié)議的 API 網(wǎng)關(guān)最省事。TaoToken 的接口地址是 https://taotoken.net/api在 OpenHarmony 的 http 模塊里按標(biāo)準(zhǔn) POST 請(qǐng)求調(diào)用即可。請(qǐng)求體里帶上 model、messages 這些字段請(qǐng)求頭帶 Authorization。返回結(jié)構(gòu)是標(biāo)準(zhǔn)的 choices 數(shù)組解析方式和你在其他平臺(tái)用 OpenAI 接口一樣。API Key 管理上建議在工程里做一層封裝把 Key 和模型 ID 放在單獨(dú)的配置模塊不要散落在各處。這樣換 Key 或者換模型時(shí)只改一個(gè)地方。Key 從 https://taotoken.net/api-keys 創(chuàng)建接入文檔在 https://taotoken.net/doc 有完整示例。如果你做的是長(zhǎng)期編碼輔助或者 Agent 類工作流可以看下 Coding Plan地址是 https://taotoken.net/coding-plan它針對(duì)持續(xù)性開發(fā)場(chǎng)景做了優(yōu)化。想先快速驗(yàn)證模型對(duì)話效果直接在 https://taotoken.net/chat 里試就行不用寫代碼?；氐焦こ瘫旧韋ull_sdk 跑通后建議做幾件事鞏固環(huán)境把成功的 SDK 版本、runtimeOS、hvigor 版本組合記錄下來把 ets-loader 的 npm install 步驟寫進(jìn)團(tuán)隊(duì)的環(huán)境搭建文檔把 build-profile.json5 的關(guān)鍵配置做成模板。這些動(dòng)作能讓團(tuán)隊(duì)里其他人少踩坑。最后提醒一個(gè)實(shí)際經(jīng)驗(yàn)SDK 版本升級(jí)時(shí)full_sdk 要跟著換runtimeOS 和 compileSdkVersion 也要同步改。三者是一個(gè)整體動(dòng)一個(gè)就要檢查另外兩個(gè)。我見過升級(jí) DevEco Studio 后忘了換 full_sdk結(jié)果編譯報(bào)一堆找不到接口的錯(cuò)排查半天才發(fā)現(xiàn)是版本沒對(duì)齊。環(huán)境搭好之后把精力放回業(yè)務(wù)代碼上。full_sdk 提供的高權(quán)限 API 能讓你做很多 public-SDK 做不了的事模型接入又能補(bǔ)上 AI 能力這兩塊配合起來OpenHarmony 工程的可玩性會(huì)高很多。