📚 课程目录第2章 nRF Connect SDK与Matter开发环境搭建

2. nRF Connect SDK与Matter开发环境搭建

Matter 应用在 Nordic 平台上并不是一个孤立的工程，而是建立在 nRF Connect SDK（NCS）之上的完整构建体系。NCS 把 Zephyr RTOS、nRF 驱动、Matter 协议栈、示例应用和工具链整合在一个由 west 管理的多仓库（multi-repo）结构中。理解这套结构，是后续编译、烧录、调试和互操作验证的前提。本节围绕工具链安装、west 工作流、SDK 版本管理、示例仓库获取以及 VS Code 与命令行构建环境配置展开，目标是让开发者在同一台机器上得到一套可复现、可切换版本的 Matter 开发环境。

一、环境组成与依赖关系

NCS 的安装可以拆成四层：主机工具链、Python 环境、west 元工具与 SDK 仓库、以及编辑器/构建前端。主机工具链包含编译器（arm-zephyr-eabi-gcc）、CMake、Ninja、dtc、GNU Make 等；Python 环境提供 west、pyelftools、nrf-regtool 等脚本依赖；west 负责拉取并管理 nrf、zephyr、matter 等仓库；VS Code 的 nRF Connect 扩展或命令行则作为构建入口。四层之间是依赖关系而非并列关系，任何一层版本不匹配都会在构建阶段暴露为难以定位的错误。

二、工具链安装与 Python 环境准备

Nordic 官方推荐使用 Toolchain Manager（随 nRF Connect for Desktop 安装）来获取工具链，它会自动下载匹配版本的编译器、CMake、Ninja 和 Python，并注册到系统中。若采用手动方式，则需要自行安装 Python 3.10 或更高版本，并创建独立虚拟环境，避免与系统 Python 冲突：

python3 -m venv ~/ncs-venv
source ~/ncs-venv/bin/activate
pip install --upgrade pip
pip install west

安装完成后用 west --version 确认版本。此时 west 只是一个空壳，还没有任何 SDK 仓库。工具链路径需要写入环境变量，例如在 Linux 下把 ~/ncs/toolchains/<hash>/opt/zephyr-sdk 加入 PATH，Windows 下由 Toolchain Manager 自动处理。判断工具链是否可用的直接方式是执行 arm-zephyr-eabi-gcc --version，能打印版本号即说明编译器就绪。

三、west 工作流与 SDK 版本管理

west 的核心是 manifest 文件。NCS 主仓 nrf 中的 west.yml 定义了该版本对应的 zephyr、matter、nrfxlib 等仓库及其 revision。因此“切换 SDK 版本”本质上就是切换 nrf 仓库的分支或标签，再让 west 同步其余仓库。典型初始化流程如下：

west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.0 ~/ncs
cd ~/ncs
west update
west zephyr-export

其中 --mr 指定 manifest revision，可以是分支名（如 main）、标签（如 v2.6.0）或提交哈希。执行 west update 后，west 会按 manifest 把每个仓库检出到指定 revision，并在 ~/ncs 下形成 nrf、zephyr、modules 等目录。west zephyr-export 则把 Zephyr 的 CMake 包注册到当前 Python 环境，使后续 find_package(Zephyr) 能正确解析。

版本管理上有两点需要特别注意。第一，Matter 示例对 NCS 版本有明确要求，例如某些 Matter 1.3 特性需要 NCS v2.6.0 及以上，混用旧版 zephyr 会导致编译失败。第二，同一台机器上可以并存多个 NCS 工作区（如 ~/ncs-2.5 与 ~/ncs-2.6），通过激活不同虚拟环境或设置 ZEPHYR_BASE 来切换，而不是在同一工作区内反复 west update 到不同标签，后者容易残留旧构建缓存。

建议为每个 NCS 版本建立独立工作区和独立 Python 虚拟环境，命名中带上版本号，例如 ncs-2.6-venv。这样在排查“同一工程在 A 机器能编译、B 机器失败”时，可以快速确认是否为版本漂移导致。

四、获取 Matter 示例仓库

Matter 示例位于 nrf/samples/matter 目录下，随 west update 一并获取，无需单独克隆。常见示例包括 light_bulb、light_switch、lock、thermostat、template 等。以 light_bulb 为例，其工程结构包含 CMakeLists.txt、prj.conf、src/main.cpp 以及板级配置文件 boards/nrf5340dk_nrf5340_cpuapp.conf。构建前应确认目标板与示例支持的板型一致，例如 nRF5340 DK、nRF52840 DK 或 Thingy:53。

若需要基于示例创建自有应用，推荐使用 west build -b <board> nrf/samples/matter/light_bulb 先验证示例可编译，再复制到工作区外的目录并修改 CMakeLists.txt 中的 find_package(Zephyr) 路径。直接修改 SDK 内示例会在下次 west update 时被覆盖。

五、VS Code 与命令行构建环境配置

VS Code 侧需要安装 nRF Connect 扩展包，并在设置中指定 NCS 工作区路径与工具链路径。扩展会自动识别 west 工作区，提供“Add build configuration”“Build”“Flash”“Debug”等操作。命令行侧则依赖环境变量：ZEPHYR_BASE 指向 ~/ncs/zephyr，PATH 中包含工具链与 west。一个可复用的构建命令如下：

west build -b nrf5340dk_nrf5340_cpuapp \
  -d build/light_bulb \
  nrf/samples/matter/light_bulb \
  -- -DCONF_FILE=prj.conf
west flash -d build/light_bulb

构建成功的标志是终端输出 Memory region Used Size 段落，并生成 build/light_bulb/zephyr/zephyr.hex。若出现 CMake Error: Could not find Zephyr，通常是 west zephyr-export 未执行或虚拟环境未激活；若出现 arm-zephyr-eabi-gcc: not found，则是工具链未加入 PATH。烧录后通过串口（115200 8N1）可看到 Matter 启动日志，包含设备初始化、Thread 或 Wi-Fi 连接状态以及配对码信息，这是判断环境是否真正可用的最终依据。

不要在同一构建目录中混用不同 NCS 版本或不同板型。切换版本或板型时应删除 build/ 目录重新构建，否则 CMake 缓存会引用旧的工具链路径和 Kconfig，导致难以解释的链接错误。

完成以上配置后，开发者应能在命令行与 VS Code 两条路径下一致地构建、烧录并观察 Matter 示例运行。环境搭建的价值不在于“装完即可”，而在于版本可追溯、构建可复现、问题可定位——这正是后续互操作验证能够稳定开展的基础。