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