你手上有一块 STM32F103C8T6 最小系统板，想用它跑点东西，比如做个串口通信、驱动个传感器，或者干脆试试 Zephyr RTOS。你兴冲冲地打开 Zephyr 官方文档，准备大干一场，结果第一步“安装 Zephyr SDK”就让你有点懵。

“SDK 是啥？必须装吗？装哪里？怎么装完还是编译不过？” 这几乎是每个 Zephyr 新手，尤其是从 Arduino、Keil 这类集成环境转过来的开发者，都会遇到的第一个门槛。很多人卡在这里，不是因为问题多难，而是因为 Zephyr 的生态和传统单片机开发环境差异太大，官方文档虽然详尽，但默认你熟悉 Linux 命令行、包管理和交叉编译工具链这些概念。

今天，我们就以STM32F103C8T6这块“国民级”开发板和Zephyr SDK 1.0.1版本为例，把安装过程掰开揉碎，不仅告诉你每一步怎么操作，更要讲清楚每一步“为什么”要这么做，以及安装完成后如何真正“用起来”，编译并烧录一个最简单的例程。我们的目标不是复述文档，而是帮你建立一套从零到一、可复现、可排查的完整工作流。

1. 先别急着下载：搞懂 Zephyr SDK 到底是什么

很多人把 Zephyr SDK 当成一个普通的“开发工具包”，类似 Keil 的安装包。这个理解偏差，是后续一系列困惑的根源。

Zephyr SDK 的核心，是一套高度集成、为 Zephyr RTOS 量身定制的交叉编译工具链集合。它不仅仅是编译器（GCC/Clang），还捆绑了构建 Zephyr 项目所必需的一系列“宿主工具”（Host Tools）。

1.1 为什么 Zephyr 需要自己的 SDK？

在传统的 STM32 开发中，你可能会用arm-none-eabi-gcc这个工具链。它确实能编译出 ARM Cortex-M 的机器码。但 Zephyr 项目要复杂得多：

1. 多架构支持：Zephyr 支持 ARM、RISC-V、x86、Xtensa 等十几种架构。如果让用户自己为每种架构找工具链，管理将是噩梦。
2. 定制化需求：Zephyr 的构建系统（基于 CMake 和 West）对工具链有特定要求，比如特定的库文件路径、对某些编译特性的支持等。官方 SDK 确保了与构建系统的完美兼容。
3. 宿主工具集成：开发嵌入式系统，编译只是第一步。你还需要：
   • QEMU：用于在电脑上模拟运行程序，快速调试，无需硬件。
   • OpenOCD：用于连接真实的硬件调试器（如 ST-Link、J-Link）进行烧录和调试。
   • 设备规则（udev rules）：在 Linux 上，让普通用户也能访问 USB 调试器，不用每次都sudo。 Zephyr SDK 把这些工具都打包好了，并且版本是经过测试、能与当前 Zephyr 版本协同工作的。

所以，安装 Zephyr SDK 不是可选项，而是高效使用 Zephyr 的强推荐起点。对于 STM32F103C8T6（属于 ARM Cortex-M3 架构），SDK 提供了对应的arm-zephyr-eabi工具链。

1.2 SDK 版本与 Zephyr 版本的“配对”问题

这是另一个关键点。输入材料中提到了Zephyrsdk1-0-1。在 Zephyr 生态里，SDK 版本和 Zephyr RTOS 的主版本存在兼容性矩阵。用错了版本，可能会导致编译失败或运行时出现奇怪问题。

• Zephyr SDK 1.0.1是一个相对较新的版本，通常与 Zephyr v3.6 及之后的版本有较好的兼容性。
• 如果你拉取的是非常老的 Zephyr 代码（比如 v2.x），可能需要使用更老的 SDK（如 0.16.x）。
• 反之，如果你用最新的 Zephyr 主分支，也可能需要最新的 SDK 测试版。

核心建议：在开始前，先确定你要使用的 Zephyr 代码版本（例如，某个稳定的 LTS 版本，如 v3.7.0），然后去官方文档查看其推荐的 SDK 版本。对于新手，我强烈建议使用一个明确的、稳定的 Zephyr 发布版本，而不是直接使用main分支，这能极大减少环境问题。

2. 实战：在 Linux 上安装 Zephyr SDK 1.0.1

我们以最常见的 Linux 环境（Ubuntu 22.04）为例，Windows 和 macOS 的思路类似，但具体命令和路径不同。Linux 环境是 Zephyr 开发的一等公民，支持最完善，也最能体现其工作流。

2.1 安装前的系统准备

Zephyr 构建依赖一些基础的开发工具。在安装 SDK 之前，最好先确保系统环境健全。

# 更新软件包列表 sudo apt update # 安装基础编译工具、CMake、Python3、Git等 sudo apt install -y --no-install-recommends \ git cmake ninja-build gperf \ ccache dfu-util device-tree-compiler \ wget python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc g++ libsdl2-dev libglib2.0-dev

为什么需要这些？

• cmake,ninja-build: Zephyr 使用 CMake 生成构建文件，Ninja 作为构建后端，速度更快。
• python3,pip: Zephyr 的元工具west以及很多脚本是用 Python 写的。
• device-tree-compiler: 用于处理硬件描述文件（.dts）。
• dfu-util: 一种设备固件更新工具，某些开发板会用到。
• ccache: 编译缓存，能显著加速重复构建。

2.2 下载、验证并解压 SDK 包

官方推荐将 SDK 安装在用户主目录（~）或/opt等标准位置。我们选择主目录，这样不需要sudo权限。

# 1. 进入用户主目录 cd ~ # 2. 下载 Zephyr SDK 1.0.1 (GNU 版本，包含所有工具链) wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz # 3. （重要）验证文件完整性，防止下载损坏 wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/sha256.sum | shasum --check --ignore-missing

如果验证通过，终端会输出类似zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz: OK的信息。如果失败，需要重新下载。

# 4. 解压下载的压缩包 tar xvf zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz

解压后，你会得到一个zephyr-sdk-1.0.1目录。请记住这个路径，后续环境变量可能会用到。

2.3 运行安装脚本并配置工具链

解压只是释放了文件，还需要运行安装脚本进行初始化和注册。

# 进入解压后的SDK目录 cd zephyr-sdk-1.0.1 # 运行安装脚本 ./setup.sh

运行setup.sh时，脚本会做几件重要的事：

1. 询问安装哪些工具链：它会列出所有支持的架构（ARM, RISC-V, Xtensa...）。对于 STM32F103，我们只需要 ARM 工具链。你可以按回车接受默认（通常是全部安装），或者根据提示选择只安装arm-zephyr-eabi以节省空间。
2. 设置 CMake 包注册：将 SDK 的路径注册到 CMake 的“包注册表”中。这样，Zephyr 的构建系统在后续编译时，能自动发现并使用这个 SDK，而无需你手动指定路径。
3. 下载缺失的工具链：如果你选择了安装某个工具链，但当前目录下没有，脚本会从网络下载。

注意：setup.sh通常只需要运行一次。如果你后续移动了zephyr-sdk-1.0.1目录，需要重新运行该脚本，以便更新注册信息。

2.4 配置 udev 规则（让普通用户能访问调试器）

这是让开发体验更顺畅的关键一步。在 Linux 上，像 ST-Link、J-Link 这样的 USB 调试器默认只有root用户能直接访问。每次烧录都要sudo很麻烦，而且可能影响 IDE 集成。

# 将 OpenOCD 提供的 udev 规则文件复制到系统目录 sudo cp ~/zephyr-sdk-1.0.1/hosttools/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/ # 重新加载 udev 规则，使其生效 sudo udevadm control --reload

执行后，重新插拔你的 ST-Link 调试器，普通用户就应该能访问/dev/ttyACM0或类似设备了。

3. 安装后的关键验证：你的 SDK 真的能用吗？

很多人安装完 SDK 后，直接跳到下一步“获取 Zephyr 源码”，结果在编译时遇到一堆“找不到编译器”的错误。问题往往出在环境变量上。

3.1 理解 Zephyr 的工具链选择机制

Zephyr 构建系统通过环境变量ZEPHYR_TOOLCHAIN_VARIANT来决定使用哪个工具链。它有以下几个常用值：

• zephyr:（推荐）告诉构建系统：“请使用 Zephyr SDK 里的工具链”。构建系统会自动在注册表或ZEPHYR_SDK_INSTALL_DIR指向的路径里寻找 SDK。
• gnuarmemb: 使用系统中已安装的 GNU Arm Embedded 工具链（即arm-none-eabi-gcc）。如果你之前装过这个，并且想用，可以设置此变量。
• llvm: 使用 LLVM/Clang 工具链。

对于新手，最稳妥的方式就是使用zephyr，并确保 SDK 已被正确注册。

3.2 如何验证 SDK 安装成功？

打开一个新的终端窗口（让环境变量生效），执行以下命令：

# 1. 检查工具链是否在 PATH 中（不一定需要，因为CMake通过注册表查找） # 但可以验证SDK的bin目录是否存在编译器 ls ~/zephyr-sdk-1.0.1/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc # 2. 更重要的验证：尝试运行一个简单的编译测试 # 创建一个临时目录和最简单的C文件 mkdir -p ~/zephyr_test && cd ~/zephyr_test cat > test.c << 'EOF' int main() { return 0; } EOF # 使用SDK中的编译器进行编译（指定目标为cortex-m3） ~/zephyr-sdk-1.0.1/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc -mcpu=cortex-m3 -mthumb -c test.c -o test.o # 检查是否生成了目标文件 file test.o

如果file命令显示输出类似test.o: ELF 32-bit LSB relocatable, ARM, EABI5 version 1 (SYSV), not stripped，并且没有报错，那么恭喜你，SDK 中的 ARM 工具链工作正常。

3.3 环境变量设置（可选但建议）

虽然 CMake 注册表能自动发现 SDK，但显式设置环境变量可以让过程更清晰，也便于在脚本或不同配置间切换。将以下内容添加到你的 shell 配置文件（如~/.bashrc或~/.zshrc）末尾：

# 设置 Zephyr SDK 安装目录（根据你的实际路径修改） export ZEPHYR_SDK_INSTALL_DIR=$HOME/zephyr-sdk-1.0.1 # 明确指定使用 Zephyr SDK 作为工具链 export ZEPHYR_TOOLCHAIN_VARIANT=zephyr

添加后，执行source ~/.bashrc或重新打开终端使配置生效。

4. 从安装到实战：为 STM32F103C8T6 编译一个 Blinky

SDK 装好了，环境也配了，是时候让它干点活了。我们用一个最简单的“点灯”程序来验证整个工具链和后续的 Zephyr 开发环境。

4.1 获取 Zephyr 源码并初始化工作空间

Zephyr 使用west这个元工具来管理源码、依赖和构建。我们首先安装west。

# 使用 pip 安装 west pip3 install --user west # 将 west 所在目录（通常是 ~/.local/bin）加入 PATH echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc source ~/.bashrc # 验证 west 安装 west --version

接下来，拉取 Zephyr 源码。建议使用一个长期支持（LTS）版本，例如 v3.7.0，稳定性更好。

# 创建一个工作目录并进入 mkdir -p ~/zephyrproject && cd ~/zephyrproject # 使用 west 初始化仓库，并指定版本为 v3.7.0 west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.7.0 # 拉取所有子模块和依赖（这步需要一些时间） west update

4.2 导出 Zephyr 环境变量

Zephyr 的构建系统需要知道ZEPHYR_BASE（源码根目录）在哪里。

# 进入 Zephyr 源码目录 cd ~/zephyrproject/zephyr # 导出 Zephyr 环境变量脚本 source zephyr-env.sh

注意：source zephyr-env.sh的效果只在当前终端会话有效。每次打开新终端进行 Zephyr 开发，都需要先进入zephyr目录执行这条命令，或者将相关环境变量写入你的 shell 配置文件。

4.3 为 STM32F103C8T6 编译 Blinky 示例

STM32F103C8T6 在 Zephyr 中对应的开发板名称通常是stm32f103c8t6或stm32f103c8t6_mini。我们可以通过west来构建示例。

# 进入一个示例目录，比如最基本的 blinky cd ~/zephyrproject/zephyr/samples/basic/blinky # 使用 west 构建，指定目标板为 stm32f103c8t6 west build -b stm32f103c8t6

命令解释：

• west build: 启动构建命令。
• -b stm32f103c8t6: 指定目标板（Board）。Zephyr 为许多开发板提供了预定义的配置文件。

如果一切顺利，你会在build目录下看到生成的文件，其中最重要的是build/zephyr/zephyr.bin（二进制文件）和build/zephyr/zephyr.elf（带调试信息的文件）。

4.4 烧录到硬件

烧录需要硬件连接（ST-Link/V2 调试器）和对应的工具。Zephyr SDK 已经包含了openocd。

1. 硬件连接：用 ST-Link 的 SWD 接口连接 STM32F103C8T6 的SWCLK(PA14)、SWDIO(PA13)、GND和3.3V。
2. 烧录命令：

   # 在构建目录下，使用 west 和 openocd 进行烧录 west flash

   west flash命令会尝试自动调用合适的烧录工具（对于 STM32，通常是 OpenOCD）。如果成功，你会看到 OpenOCD 的输出信息，并且板子上的 LED（如果电路连接了 PC13）应该开始闪烁。

如果west flash失败怎么办？这是新手最常见的坑。请按以下顺序排查：

1. 权限问题：是否执行了2.4节的 udev 规则配置？重新插拔调试器，尝试用lsusb查看是否能识别到 ST-Link。
2. 连接问题：检查 SWD 线是否接好，板子是否供电。
3. OpenOCD 配置：west flash依赖于板子的配置文件。对于stm32f103c8t6，Zephyr 通常有内置配置。如果不行，可以尝试手动指定 OpenOCD 命令：

   openocd -f board/stm32f103c8t6.cfg -c "program build/zephyr/zephyr.bin verify reset exit"

   你需要根据你的具体硬件，找到正确的.cfg文件路径（可能在 SDK 或 Zephyr 源码的boards/目录下）。
4. 使用其他工具：你也可以使用st-flash（ST官方工具）或pyocd进行烧录，但这需要额外安装。

5. 超越安装：建立可持续的 Zephyr 开发工作流

成功点亮 LED 只是第一步。要让 Zephyr SDK 和整个环境为你长期服务，还需要理解几个工程实践。

5.1 管理多个 SDK 和 Zephyr 版本

你可能会同时参与多个项目，它们要求不同的 Zephyr 版本，进而需要不同的 SDK。Zephyr 支持这种场景。

• 多个 SDK 并存：你可以下载多个版本的 SDK，解压到不同的目录，例如~/zephyr-sdk-0.16.5和~/zephyr-sdk-1.0.1。通过设置ZEPHYR_SDK_INSTALL_DIR环境变量来切换。甚至，你可以将这个变量指向一个父目录（如~/sdks），里面放多个 SDK 子目录，构建系统会自动选择兼容的版本。
• West 工作空间管理：west init创建的是一个“工作空间”（workspace）。你可以为不同的项目创建不同的工作空间目录，每个里面初始化不同版本的 Zephyr。通过source <workspace>/zephyr/zephyr-env.sh来切换环境。

5.2 理解构建目录和配置

每次west build都会在项目目录下生成一个build文件夹。这里面包含了所有中间文件、最终镜像和最重要的.config文件（Kconfig 配置）和build.ninja文件。

• 清理构建：west build -t clean或直接删除build目录。
• 修改配置：west build -t menuconfig可以启动一个图形化界面来调整内核配置（如线程栈大小、功能模块使能等）。这对于优化程序大小和功能至关重要。
• 构建类型：默认是调试构建（带符号信息）。你可以通过-DCMAKE_BUILD_TYPE=Release等 CMake 参数进行发布构建。

5.3 从示例到自己的项目

不要一直待在samples目录里。创建自己的项目：

# 在工作空间外创建一个新项目目录 mkdir ~/my_zephyr_app && cd ~/my_zephyr_app # 使用 west 创建一个新应用 west init -l # 在当前目录初始化一个本地仓库 # 或者，更常见的是，手动创建项目结构： mkdir src # 在 src 目录下放置你的 .c 源文件 # 创建 CMakeLists.txt 和 prj.conf 文件

你需要学习如何编写CMakeLists.txt来告诉构建系统如何编译你的代码，以及prj.conf来设置项目特定的 Kconfig 选项。最好的学习方式就是复制一个简单的示例（如blinky），然后修改它。

安装 Zephyr SDK 不是目的，而是开启现代嵌入式开发的一把钥匙。这个过程的核心，是从“针对单一芯片的 IDE 开发”思维，转向“基于框架、工具链和命令行的项目化开发”思维。你会开始接触 CMake、设备树、Kconfig、West，这些是 Zephyr 强大可移植性和模块化的基石。

对于 STM32F103C8T6 这样的经典硬件，Zephyr 提供了一条从裸机思维升级到 RTOS 框架思维的清晰路径。而 SDK 的顺利安装，是踏上这条路径的第一个、也是最重要的脚印。当你的 LED 按照 Zephyr 的线程调度规律闪烁时，你运行的已经不再是一个简单的while(1)循环，而是一个小型、实时、可扩展的操作系统内核。