1. 项目概述NCS到底是什么为什么值得折腾我最早接触NCSnRF Connect SDK的时候是被它折磨得够呛。那时候项目要用nRF5340做低功耗音频官方资料全指向NCS但整套环境装了三天才跑通中间踩的坑多到可以写一本《NCS安装排错指南》。后来陆续帮几个团队搭过环境发现大家遇到的问题出奇一致不是不会写代码而是环境根本起不来。先说清楚NCS是什么。nRF Connect SDK是Nordic官方推出的统一软件开发套件它不是一个独立的东西而是基于Zephyr RTOS封装的一整套方案里面整合了Zephyr内核和驱动框架设备树、线程调度、电源管理都靠它Nordic自家的协议栈SoftDevice ControllerBLE Controller、802.15.4、Matter、Thread、Zigbee板级支持包nRF5340、nRF52840、nRF9160这些芯片的BSP应用程序层库DFU设备固件升级、MCUboot引导程序、传感器驱动、Logger等等编译器与工具链管理west工具、Arm GCC编译器、nrfjprog烧录工具全部由SDK统一管起来换句话说NCS就是把“芯片寄存器操作 协议栈 RTOS 编译烧录 调试”整条链路打包成一套东西让开发者只需要关心业务逻辑不用回到寄存器级写代码。对于做低功耗蓝牙、Mesh、Thread、Matter这类产品的团队NCS基本是绕不开的。这篇博文适合谁看想用nRF52840/nRF5340做产品原型验证的硬件工程师刚进入嵌入式无线领域的学生以及被环境安装劝退过准备重新来一遍的人。我会把你需要知道的都捋清楚尤其是一些文档里不会写、只有踩过坑才懂的细节。2. 工具链方案选型为什么我推荐VS Code 插件这条路2.1 三条安装路线对比NCS的安装方式目前主流有几种我先把优缺点摆出来。路线一nRF Connect for Desktop图形化安装Nordic提供一个桌面应用可以在Windows/macOS/Linux上通过图形界面装SDK和Toolchain。对新手来说入门友好点几下就能装好。但我个人不太推荐作为主力方案原因后面细说。路线二命令行 VS Code nRF Connect for VS Code插件把nRF Command Line Tools、west、Python工具链都装在系统里然后通过VS Code的Nordic插件来管理SDK、编译和烧录。这也是我目前主力使用的方式。路线三纯命令行west Zephyr SDK完全不用VS Code直接用west命令构建、烧录配合Makefile或Ninja。适合习惯终端工作流、不需要IDE的老手。下面是三种方案的横向对比方案上手难度可定制性稳定性适合场景nRF Connect for Desktop低低中等快速评估、第一次接触VS Code 插件中中高高日常开发主力纯命令行高高高脚本构建、CI/CD我自己的习惯是评估阶段用桌面工具快速跑demo一旦开始写正式代码立即切到VS Code方案。桌面工具的问题在于它把SDK版本和Toolchain捆绑管理有时候想用特定commit的SDK图形界面反而不好操作而VS Code插件本质上是west命令的图形化封装底层该干嘛还是干嘛灵活性和可控性都更好。2.2 为什么强烈建议配合Zephyr来理解NCSNCS大量代码实际上来自Zephyr上游只是Nordic在它的基础上做了适配和扩展。你打开NCS的zephyr目录会发现这根本就是一个Zephyr的fork。所以很多时候搜问题的答案直接搜Zephyr相关文档也能找到只不过要注意NCS版本对应的Zephyr版本是多少。这一点不是废话它直接影响安装和使用方式。NCS的构建系统和Zephyr完全一致都是用west管理多仓库用CMake Ninja构建。所以安装NCS环境本质上你也在装一套Zephyr开发环境。理解了这个关系后面遇到问题排查起来会快很多。3. 安装前的准备工作硬件、系统和依赖3.1 硬件与系统需求先列一下最基本的硬件需求一块Nordic开发板推荐nRF5340 DK或者nRF52840 DK。没有DK的话用第三方模块比如在淘宝上买的那种nRF52840最小系统板也勉强能跑但调试体验会差。至少你要有SWD接口能连J-Link一条USB线最好是数据线不是只能充电的那种。别笑我见过不止一个人拿充电线连了半天发现识别不到设备一个J-Link调试器。Nordic DK板载了J-Link OB所以买DK最省事如果用第三方模块你可能需要一个独立的J-Link或者ST-Link配合OpenOCD也能用但不推荐操作系统方面Windows 10/11、Ubuntu 20.04、macOS 11都支持。我主力在Windows上开发Linux也时不时用两边踩坑点不一样后面都会提到。3.2 Windows/Linux/macOS通用依赖以Windows为例你需要在安装NCS之前把以下东西准备好第一安装nRF Command Line Tools这是Nordic提供的命令行工具包里面包含nrfjprog烧录工具、J-Link驱动等。去Nordic官网下载最新版本安装时注意勾选“Add to PATH”。版本上建议选新不选旧但也不要过于激进地用beta版。安装完成后命令行里执行nrfjprog --version能输出版本号就说明正常。第二安装Python 3NCS大量脚本依赖Python包括west工具本身。建议装Python 3.8到3.11之间的版本过新的版本比如3.12有时候会碰到一些第三方库不兼容的问题。装的时候有一个关键点一定要勾选“Add Python to PATH”。我见过太多人栽在这一步Python装完了但命令行敲python没反应。第三安装GitWindows上从git-scm.com下载安装即可。安装时默认选项就够用但建议在“Adjusting your PATH environment”这一步选择“Git from the command line and also from 3rd-party software”这样后面VS Code终端里也能直接用git命令。第四安装VS Code这个不用多说安装完记得装一个C/C扩展ms-vscode.cpptools后面看代码跳转和编译排错都会用到。LinuxUbuntu上的依赖稍有不同主要是sudo apt update sudo apt install -y 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 gcc-multilib g-multilib libsdl2-devmacOS的话需要先装Homebrew然后brew install cmake ninja python3 git之类的整体类似这里不展开。3.3 为什么Python版本和pip工具链容易出问题NCS的构建体系里Python不是拿来写应用代码的它主要是支撑west工具、构建脚本、以及各种生成器脚本。这意味着你本机的Python环境必须干净、可预期否则极易出现“明明SDK装对了一编译就报错”的尴尬局面。我强烈建议在用户目录下创建一个虚拟环境来承载NCS的Python依赖python -m venv ncs-env这样后续pip安装west就不会污染系统Python多个项目之间也不会因为版本冲突互相干扰。后面安装west的时候我也会用这个虚拟环境来操作。4. 实操流程从零到跑通Blinky例程4.1 west工具的安装与配置先激活刚才创建的虚拟环境# Windows (PowerShell) ncs-env\Scripts\Activate.ps1 # Linux / macOS source ncs-env/bin/activate然后安装westpip install west安装完成后验证版本west --version能输出版本号就OK。如果你看到类似ModuleNotFoundError的错误先检查是不是没有激活虚拟环境或者pip版本太旧需要先升级pip install --upgrade pip4.2 拉取NCS SDK源码NCS用west管理多个仓库拉取SDK的命令是west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.0 ncs这里-m指定manifest仓库地址--mr是指定版本标签。版本选择非常关键新手最容易在这里踩坑你装的nRF Command Line Tools、VS Code插件、以及SDK版本三者之间需要兼容但官网不会很醒目地做一张兼容性对照表。我的建议是第一次安装选择最新的release版不要去追main分支的每日构建。例如当前稳定版本可能是v2.6.0或者v2.x.y去GitHub Releases页面看最新的tag就行。main分支虽然可能包含一些新特性但不保证稳定编译报错你都没处查。执行完init命令后进入ncs目录拉取所有子仓库cd ncs west update这一步会拉取Zephyr内核、Nordic的HAL库、各种协议栈仓库等几十个仓库耗时取决于网络状况。在网络不好的情况下容易中断此时重新执行west update即可它会断点续传。如果你经常遇到网络问题可以考虑配置Git的代理也可以在仓库里修改west config来增加parallel参数加快拉取速度。west update完成后目录结构大致如下ncs/ ├── bootloader/ ├── modules/ ├── nrf/ ├── zephyr/ └── .west/4.3 安装Python依赖NCS的很多脚本需要额外的Python包包括pyelftools、intelhex等。官方给了一个requirements文件直接装pip install -r zephyr/scripts/requirements.txt pip install -r nrf/scripts/requirements.txt有时候因为网络问题某些包安装失败重试即可。装完后建议顺手升级一下westpip install --upgrade west到这里SDK和工具链的骨架已经搭好但还不能编译因为还差编译器。4.4 编译器与Toolchain安装这一部分最容易被忽略NCS支持用Zephyr SDK自带的交叉编译器也可以单独装Arm GCC工具链。官方推荐的是Zephyr SDK因为它包含了适用于Arm Cortex-M全系列芯片的编译器、调试工具链、以及QEMU之类的模拟器。到Zephyr官方GitHub Releases页面下载对应版本的Zephyr SDK比如zephyr-sdk-0.16.5-1。注意要选setup脚本能跑的那个tar包Windows用户选.exe安装包。以Linux为例下载后解压然后运行tar xvf zephyr-sdk-0.16.5-1.tar.xz cd zephyr-sdk-0.16.5-1 ./setup.sh -t allWindows用户直接运行安装程序一路next即可。安装时有一个选项是添加环境变量一定要勾选。然后还需要确认ZEPHYR_TOOLCHAIN_VARIANT环境变量Zephyr SDK安装后会自动配置一般不用手动改。如果你想验证是否装好可以打开一个终端进入ncs/zephyr目录执行west build -b nrf5340dk_nrf5340_cpuapp -d build-test zephyr/samples/hello_world这个命令会尝试构建一个hello_world如果工具链没装好这一步就会报错。我第一次装的时候就是在这一步发现SDK版本和编译器版本不匹配报了一个toolchain not found的错折腾了半天才发现是Zephyr SDK版本太老。4.5 构建Blinky例程并烧录工具链装好后我们来真正跑一个例程。Blinky是LED闪烁的示例复杂度低用来验证“编译→烧录→运行”这条链路是否通畅最好不过。cd ncs west build -b nrf5340dk_nrf5340_cpuapp -d build/blinky nrf/samples/blinky说明一下参数含义-b开发板类型nrf5340dk_nrf5340_cpuapp表示nRF5340 DK上的应用核nRF5340是双核一个负责应用一个负责网络协议-d构建目录生成的编译产物会放在这里最后一个参数是源码路径如果是nRF52840 DK把-b换成nrf52840dk_nrf52840即可。构建完成后插上开发板Windows可能需要装一下驱动。然后烧录west flashwest flash内部会调用nrfjprog找到J-Link并下载固件。正常情况下你会看到板子上的LED开始闪烁这就说明整个环境已经通了。从安装到跑起来整个过程快的话30分钟慢的话可能折腾一两天。最耗时的往往是各种依赖没装齐、环境变量没配置好导致的一连串报错。5. nRF Connect for VS Code插件的安装与使用细节5.1 为什么你需要它命令行方式能跑通以后日常开发我还是推荐用VS Code插件。原因很实在west build之类的命令不用每个都手敲插件会把可用的开发板、例程、构建配置在界面里列出来点一点就行。同时编译输出直接以问题面板的形式展示出错跳转到对应代码行省去了一行一行看log的时间。5.2 插件安装与配置步骤VS Code插件市场搜索nRF Connect for VS Code作者是Nordic Semiconductor直接安装即可。装完左侧会出现一个Nordic的logo图标。第一次打开插件面板它会提示你选择SDK路径。这个时候选择我们刚才拉取的ncs目录插件会读取这个SDK的版本信息和west配置。配置完成后插件提供几个核心功能Welcome面板快速打开SDK文档、创建新项目Application视图管理你创建的应用项目编译、烧录都在这里操作分析工具查看设备树、内存占用、构建大小等非常实用我日常用得最多的是Create a new application功能。它本质上是让你选择一个例程模板然后复制到你自己的工作目录。比起手动创建文件结构这个方式显然不容易出错。5.3 插件容易踩的坑第一SDK路径中不要有中文或空格。Windows上如果你把SDK放在C:\Users\张三\Documents\NCS这种路径插件经常会莫名其妙报错。建议就放C:\ncs这一类干净路径下。第二VS Code和插件有版本兼容问题。新版本插件可能要求VS Code更新到特定版本以上。如果插件面板白屏或者功能按钮灰色不可点先去看插件日志输出面板里选nRF Connect一般都能找到线索。第三如果你同时装了多个SDK版本插件会让你选当前用哪个。这里要小心不同版本对应的编译器版本可能不同如果lexicon不对编译器会报错。建议一个项目固定一个SDK版本不要随便切。6. 常见问题与处理技巧我实测过的排错思路6.1 编译报错“west: command not found”这是最常见的问题。多半是你没有激活Python虚拟环境或者pip安装路径没有加入PATH。排查思路# Windows PowerShell which west # 或者 where.exe west如果提示找不到先确认pip show west是否安装了如果安装了但找不到命令很可能是因为Python Scripts目录不在PATH中。Windows上一般路径是C:\Users\[用户名]\AppData\Roaming\Python\Python3xx\Scripts把它手动加到PATH即可。如果是使用了虚拟环境记得激活ncs-env\Scripts\Activate.ps1 # Windows source ncs-env/bin/activate # Linux/macOS6.2 编译报错“No such file or directory: cmake”NCS依赖CMake 3.20以上版本但很多系统自带的CMake版本比较旧。另外Windows用户如果用了VS的C工作负载CMake可能被VS的版本抢先占用了PATH导致west找不到正确的CMake。建议安装独立的最新版CMake去官网下载或者scoop install cmake并确保新版CMake路径排在PATH前面。处理完后重启VS Code让环境变量重新加载。6.3 烧录时报“Could not connect to target”或“No debug probe found”硬件连接问题。排查顺序USB线换一根确认是数据线开发板背面有一个Power指示灯亮了才有戏nrfjprog --ids看看能不能识别到J-Link序列号如果识别不到装上J-Link对应驱动。Windows 10以上一般自动识别老旧驱动可能需要卸载重装另外nRF5340 DK有个特点它是双核芯片复位和调试都需要应用核和网络核配合。如果CPUapp烧过特定的固件导致调试接口被锁可以用nrfjprog --recover恢复nrfjprog --recover这条命令会擦除芯片全部内容并恢复默认调试使能状态。注意这会抹掉所有固件执行前确认你真的不用保留数据。6.4 构建速度慢有没有办法加速NCS拉取了几十个仓库首次构建编译所有依赖库确实很慢。有两个办法编译时加-j参数增加并行度最多建议不超过CPU核心数的2倍。west build -j 16在某些机器上能明显加快开启ccache。Zephyr本身支持ccache只要系统装有ccache它会自动启用。Windows用户可以用scoop install ccache安装我实测在8核16线程的机器上首次编译blinky大约需要3-5分钟第二次因为缓存生效能快一半以上。如果是大型工程例如带Matter协议栈的项目首次编译可能超过半小时做好心理准备。6.5 常见问题速查表现象可能原因解决方法west 命令找不到Python环境/虚拟环境未激活激活虚拟环境检查PATHcmake 报错CMake版本过旧或路径冲突安装新版CMake并调整PATH烧录连接不上驱动问题/USB线问题/芯片锁死换线、确认J-Link驱动、必要时recover编译时报头文件缺失SDK子仓库未完整拉取重新执行west update插件白屏VS Code版本过旧或插件冲突升级VS Code查看输出日志Python包安装失败网络问题或Python版本太新镜像源安装或更换Python版本板子LED不闪烁烧错核nRF5340或构建配置不对确认-b参数对应CPUAPP7. 后续还能怎么用设备树修改、Matter与无线协议栈跑通了Blinky只是迈出了第一步。NCS真正的价值在于它把低功耗蓝牙、Thread、Matter这些复杂协议栈封装好了让应用开发可以直接调API。以BLE为例在NCS里创建一个外设广播的工程你不需要手动初始化射频、调制解调器这些东西直接调用bt_enable、bt_le_adv_start这些API就行。配合设备树Device Tree的功能你可以直接改dts文件来配置引脚和外围设备不需要去翻寄存器手册。Matter场景下NCS的支持也比较成熟。你可以用west build -b nrf5340dk_nrf5340_cpuapp nrf/samples/matter/light_bulb这类命令直接把Matter灯控demo编译出来。当然Matter本身依赖的组件非常多首次编译时间会很长而且需要Python依赖中有一个额外的matter-environment脚本做初始化这一步经常有人漏掉导致编译报错。如果后续做量产DFUDevice Firmware Upgrade设备固件升级也完全绕不开。NCS提供MCUboot引导程序和DFU库配合nRF Connect for Desktop的Programmer工具或者nrfjprog就可以实现固件的签名和升级。由于SDK版本不同接口有差异建议先把官方nrf/samples/dfu下的例子跑一遍再集成到自己的项目里。8. 我对这套环境的一些实际体会把NCS装好只是入门真正要用得顺手我个人的经验是尽量理解NCS背后的Zephyr构建体系。很多人觉得west命令复杂其实它就是帮你处理多仓库管理和构建调度的工具。多看几遍west build --help的输出多试几次不同参数慢慢就熟了。还有一个建议每次SDK升级前先跑一个小例程验证环境是否正常再升级你的业务代码。我吃过一次亏从v2.4升到v2.5之后一个用了很久的工程编译直接报设备树错误排查发现是某个设备树绑定的API变了费了不少工夫。后来我专门建了一个“环境验证工程”每次升级后先编译一遍它确认无误再去动其他项目。最后再分享一个小技巧如果你要在多台电脑之间同步开发环境直接把ncs目录整个打包拷贝过去比重新拉取快得多。但要注意Zephyr SDK和Python依赖不需要跟着拷贝到新机器上重新安装即可因为这两个东西和操作系统的绑定很紧跨平台复制经常会出诡异问题。