本文是 Zephyr 項目管理體系的高階解構與實戰指南，全面覆蓋 west 構建系統原理、模塊解耦與 west.yml 多模塊維護機制，結合企業級多平臺 CI/CD 落地流程，深入講解如何構建可靠、可維護、跨芯片架構的一體化 Zephyr 工程。

---

一、為什么 Zephyr 需要 west 構建系統？

背景：Zephyr 是一個高度模塊化、多平臺適配的嵌入式操作系統

• 支持幾十種芯片架構（ARM Cortex-M, RISC-V, x86, ARC...）

• 擁有多個模塊（主倉庫 + HAL + BLE + FS + 模擬器等）

• 模塊分布在數十個 Git 倉庫，版本組合復雜

• 項目構建需要嚴格依賴關系管理 + 工具鏈對齊 + 平臺定制

west 的出現就是為了“模塊調度 + 工具鏈封裝 + 構建流程標準化”，將 Zephyr 從分散代碼堆變成結構化工程體系。

---

二、west 的本質：一個多倉庫構建調度與模塊集成系統

🧱 west 工具包含三層能力：

能力層級	作用描述
工程調度器	項目初始化（west init）、模塊下載（west update）
構建封裝器	跨平臺編譯（west build）、燒錄（west flash）、調試（west debug）
元數據管理器	跟蹤工程布局 .west/config + west.yml 模塊清單

它像 git + make + repo 的組合體，將分散的構建指令和模塊依賴整合成一套工具集。

---

三、west 工作流結構梳理

一個完整的 west 工程流程圖：

初始化階段：git clone zephyrwest init -l zephyr/west update構建階段：west build -b <board> <app_dir>west flash / debug / run模塊維護：west.yml → module1, module2...west update  → 自動拉取模塊CI/CD 自動化：west manifest --freeze構建多個平臺，歸檔 firmware + .config

工程目錄典型結構：

zephyrproject/
├── .west/                  ← 工程元數據
├── zephyr/                 ← 主倉庫，含 kernel、build logic、west.yml
├── modules/hal/stm32/      ← HAL 子模塊（通過 west.yml 管理）
├── modules/lib/lvgl/       ← 第三方 GUI 庫
├── tools/                  ← 構建依賴工具如 dtc
├── app/                    ← 自己的業務代碼與 CMakeLists.txt

---

四、west.yml：項目大腦

Zephyr 模塊化依賴的核心就在于 manifest 文件 west.yml。這是整個項目的 模塊清單 + 結構定義 + 依賴鎖定點。

west.yml 最小示例：

manifest:projects:- name: hal_stm32path: modules/hal/stm32revision: v1.11.0url: https://github.com/zephyrproject-rtos/hal_stm32self:path: zephyr

核心字段解構：

字段	說明
name	模塊名，west update <name> 用于更新指定模塊
path	模塊放置位置，建議結構化路徑如 modules/hal/...
revision	可指定分支、標簽、commit，保障版本一致性
url	倉庫地址，可支持 GitHub、Gitee、GitLab 等
self	指定當前 manifest 所在主倉庫路徑（通常是 zephyr）

模塊繼承（import）機制：

import:path-prefix: modules/libname-allowlist:- lvgl

用于將其他倉庫的 manifest 導入，并自動引入其模塊。

---

五、構建機制詳解（west build）

典型構建流程（示意圖）：

west build├──> cmake 配置│    └──> 生成 build.ninja├──> Kconfig 階段│    └──> .config + autoconf.h├──> DTS 階段│    └──> zephyr.dts + devicetree_unfixed.h└──> ninja 構建（最終生成 elf / hex / bin）

支持目標（-t）構建命令：

west build -t flash       # 編譯+燒錄
west build -t menuconfig  # 圖形化配置界面
west build -t ram_report  # 顯示 RAM 分布情況
west build -t size        # 顯示鏡像大小

構建多平臺建議：

• 每個 board 使用不同構建輸出目錄：-d build/<board>

• 使用 prj.conf + overlay.conf 管理配置差異

• 可使用多個 app 源目錄，對應不同項目

---

六、CI/CD 構建系統設計

構建目標：

• 每次 push / PR 自動完成構建驗證

• 支持多個目標板（STM32、nRF、ESP）并行構建

• 構建產物包括：hex、elf、.config、map、版本信息

• 對于發布版本，執行簽名 + OTA + Release 上傳

推薦工具鏈組件：

任務	工具
拉代碼	GitHub Actions / GitLab CI
Python 環境管理	venv
west / SDK 安裝	west + zephyr-sdk
多平臺并行構建	matrix 策略
OTA 構建產物上傳	GitHub Release / scp / curl

---

七、CI 實戰配置案例（GitHub Actions）

jobs:build:runs-on: ubuntu-lateststrategy:matrix:board: [nucleo_f401re, nrf52840dk_nrf52840]steps:- name: Checkout codeuses: actions/checkout@v3- name: Install west & SDKrun: |python3 -m venv venvsource venv/bin/activatepip install westwget https://.../zephyr-sdk.run && chmod +x *.run && ./zephyr-sdk.runexport ZEPHYR_TOOLCHAIN_VARIANT=zephyrexport ZEPHYR_SDK_INSTALL_DIR=$PWD/zephyr-sdk- name: Buildrun: |source venv/bin/activatewest init -l .west updatewest build -b ${{ matrix.board }} app -p always- name: Archive firmwareuses: actions/upload-artifact@v3with:name: firmware-${{ matrix.board }}path: build/zephyr/zephyr.hex

---

八、模塊版本鎖定與 freeze 策略

對于大型團隊協作、多模塊交錯開發場景，保持模塊版本一致性至關重要。

推薦做法：

1. 所有模塊統一從 west.yml 獲取版本

2. PR 中若需修改模塊版本，必須更新 revision 字段

3. 發布版本前執行：

west manifest --freeze > manifest.lock.yml

1. CI 中使用凍結版本確保構建可復現

2. 上游模塊變更觸發主倉構建任務，通過 GitHub webhook 實現模塊間集成

---

九、多平臺協作與私有模塊接入策略

推薦結構：

zephyrproject/
├── west.yml
├── modules/hal/
│   ├── hal_stm32
│   └── hal_esp32
├── modules/ble/
│   ├── my_ble_stack
├── modules/drivers/
│   ├── adc_ext
│   └── led_ctrl

私有模塊接入技巧：

• 統一 remote 地址管理：

remotes:- name: mycorpurl-base: https://gitee.com/mycorp

• 設置子模塊專屬路徑：

projects:- name: my_drvremote: mycorppath: modules/drivers/my_drvrevision: main

---

十、總結與建議

模塊	建議做法
構建系統（west）	使用 west build 封裝編譯邏輯，統一管理輸出目錄
模塊清單（west.yml）	結構化定義模塊路徑，鎖定 revision，避免 HEAD 波動
CI 構建流程	使用 matrix 并行構建，導出 hex + .config + .map
私有模塊擴展	使用 remote + path 顯式管理，兼容子倉平臺部署

只有掌握了 west 的工作原理、模塊機制與構建流程，你才真正擁有了構建大規模 Zephyr 系統的能力。

下一篇將進入 Zephyr DTS 設備樹、板卡支持包（BSP）、驅動擴展框架的高級開發主題，敬請期待。