刚拿到第一块nRF5340开发板那会儿我第一反应不是去看例程而是被nRF Connect SDKNCS的安装流程给拦住了。网上关于NCS的中文资料虽然不少但大多只讲“点哪里下一步”没讲清楚这套环境为什么会这么装、装完之后目录是什么结构、出了问题又该怎么查。这篇文章把我从零开始装NCS的完整过程摊开写覆盖Windows和Linux两条路线尽量让你照着操作就能把开发板上的blinky跑起来。如果你正准备入坑Nordic的nRF52、nRF53或者nRF91系列这篇内容应该能帮你省下至少半天折腾时间。先说结论NCS安装本身不复杂复杂的是它依赖的组件太多版本匹配关系又绕。只要理解了它的底层结构后面遇到什么报错都不慌。1. 装NCS之前先把这套生态的底细摸清楚1.1 NCS到底是什么和旧版nRF5 SDK有什么区别NCSnRF Connect SDK是Nordic半导体推出的新一代软件开发套件用来开发nRF52系列、nRF53系列、nRF91系列这些芯片同时也支持Nordic自家的Wi-Fi、蓝牙、Thread、Matter、Zigbee等无线协议方案。它跟老一代的nRF5 SDK完全是两套体系这点很多刚接触的朋友会搞混。老款nRF5 SDK是传统方式把驱动程序、协议栈、例程都打包在一个静态库里你打开Keil或者IAR直接编译就能用。优点是上手快缺点是扩展性差芯片型号一换、协议栈一变工程的移植成本就上来了。NCS则完全不同它底层集成了Zephyr RTOS整个SDK实质上是一个由多个Git仓库组成的代码集合包括sdk-nrf、sdk-zephyr、sdk-nrfxlib、sdk-mcuboot等通过west这个多仓库管理工具统一组织。从使用体验上说nRF5 SDK像一套精装修的固定户型拎包入住NCS更像一套带积木的装修平台框架是固定的但每个房间怎么布置、放什么家具都由你自己用Kconfig和设备树来配置。这套机制对量产项目特别友好因为你可以把产品需要的功能用配置项一个个打开不需要的功能直接裁剪掉固件的体积和功耗都能压得很低。需要明确的是NCS并不仅仅是一个“安装包”它的完整环境由三部分组成。第一部分是工具链里面包含编译器、链接器、CMake、Ninja等构建工具第二部分是SDK源码也就是上边提到的那些Git仓库第三部分是烧录和调试工具比如nrfjprog、nrfutil以及J-Link驱动。这三者缺一不可而且版本之间需要严格匹配这也就是为什么很多人在安装时会卡住——不是某个工具装不上而是工具链和SDK的版本对不上。1.2 两条安装路线图形化Toolchain Manager VS 命令行nrfutil安装NCS有两条主流路线你可以根据自己的使用环境来选。第一条是使用nRF Connect for Desktop桌面包里面的Toolchain Manager这是图形化工具Windows用户用起来最方便基本就是选择版本、点击安装工具链和SDK源码都会自动处理好。第二条是使用Nordic官方提供的nrfutil命令行工具适合Linux环境、服务器场景以及需要自动化构建的CI/CD流程。我的建议是新手、主力开发机是Windows、只想尽快把demo跑起来的直接用Toolchain Manager老手、主力环境是Ubuntu、需要批量管理多个NCS版本或者不想装桌面应用的直接用nrfutil。这里特别提醒一句尽量不要混用。比如有人在Toolchain Manager里装了工具链然后又用系统Python的pip单独装了一个west两边版本一旦不一致编译的时候会出现各种莫名其妙的问题。因为在NCS的环境里west、工具链、SDK是绑定的拆开处理等于自己给自己挖坑。2. 安装前的准备少走弯路的关键一环2.1 硬件和系统环境清单在正式动手安装之前先对照一下你的硬件和系统是否满足基本要求。主控方面我建议至少准备一块Nordic官方的开发板比如nRF52840 DK、nRF5340 DK或者nRF9160 DK。如果只是学习的话nRF52840 DK性价比很高社区资料也最多。如果没有官方板用第三方的nRF52840模块加一个J-Link调试器也可以但整个流程的变量会多一些出现问题时不好定位是SDK的问题还是硬件连接的问题。系统方面Windows 10/11和Ubuntu 20.04以上版本都是合适的。我自己主力机是Windows 11另外有一台Ubuntu 22.04的机器专门用来做构建验证两条路线都实测过。内存建议16GB以上尤其是nRF5340这类双核芯片在编译Matter或较复杂的工程时很吃内存内存小的机器编译时间会长很多。磁盘空间是很容易忽略的一项NCS整套环境安装完工具链加上SDK源码以及编译产生的中间文件占用空间一般在10GB到15GB如果再算上多个版本的SDK并存建议预留20GB以上。还有一个小细节安装路径尽量不要带中文、不要带空格。Zephyr的构建系统对路径比较敏感我以前见过有同事把SDK放在“桌面\新项目”这种路径下结果编译时各种诡异的报错把文件夹改成就地解决了。Windows用户尤其注意默认路径是C:\Users\你的用户名\ncs这个没问题但如果你的用户名本身是中文可能也会带来一些麻烦这种情况下建议用另一个纯英文的路径。2.2 软件依赖和仓库源准备在安装NCS之前有几个基础软件建议先准备好。首当其冲的是Git因为NCS的所有SDK源码都是通过Git拉取和更新的Windows下装Git for Windows就行安装的时候保持默认配置即可。然后是Visual Studio Code虽然命令行走天下的人可以不装但nRF Connect官方提供了一套VS Code插件从建工程、配置Kconfig到编译烧录都能在IDE里完成对新手和日常调试都非常实用。最后是Python环境这里有个关键认知需要纠正如果你用Toolchain Manager安装工具链那么工具链内部会自带一套完整的Python环境你不需要在系统里单独安装Python更不建议画蛇添足用系统Python去装west。只有在纯命令行并且自己管理工具链的时候才需要手动处理Python依赖。网络方面也需要提前确认。NCS需要从GitHub拉取多个仓库所以在正式开始安装前建议先测试一下能否正常访问GitHub和Nordic官网。如果在公司网络环境或者本地有可用的HTTP代理可以提前给Git配置好比如执行git config --global http.proxy地址端口这样能避免后续west update的时候反复超时。另外Git仓库下载大文件时需要缓冲区设置否则偶尔会出现“error: RPC failed”这类问题。我习惯在新机器上执行两条命令提前规避git config --global http.postBuffer 524288000和git config --global core.compression 0。这两条不是官方文档里的标准步骤但实测对下载大仓库很有效。3. Windows下完整安装流程从空白电脑到跑起blinky3.1 安装nRF Connect for Desktop与Toolchain ManagerWindows下的安装路径是最省心的因为它有官方的图形化工具帮你兜底。第一步去Nordic官网下载nRF Connect for Desktop这个安装包这就是一个桌面应用安装完成后打开它左侧菜单栏里会看到一排工具我们需要的是Toolchain Manager这一项。如果列表里没有可以在右上角或者菜单里手动添加安装这个工具具体位置可能会随版本有小变化但找“Toolchain Manager”这个名字就行。打开Toolchain Manager之后主界面上会列出当前可安装的NCS版本列表你可以看到类似v2.6.0、v2.7.0这样的版本号。选择一个版本点击安装。这里要说明一下这一步安装的是两样东西一是对应版本的工具链二是SDK源码。工具链默认会安装在C:\Users\你的用户名\ncs\toolchains目录下SDK源码默认在C:\Users\你的用户名\ncs\v2.6.0这样的目录下。整个安装时间取决于你的网速因为要拉取的内容不少耐心等待就行。安装完成之后Toolchain Manager界面会变成“打开”状态。点击“打开”之后工具可以选择直接启动VS Code并加载这个SDK工作区。这里有一个细节容易忽略如果你还没有安装nRF Connect for Visual Studio Code扩展建议先到VS Code扩展市场里搜索“nRF Connect for Visual Studio Code”安装Nordic官方提供的那个扩展然后再回到Toolchain Manager点击“打开”。顺序反了的话扩展可能识别不到已经安装的SDK需要额外手动指定路径。3.2 用VS Code打开SDK并创建第一个工程当VS Code加载好SDK工作区后左侧活动栏会出现一个nRF Connect的图标。点击它会看到分区面板其中有一个区域专门用来管理应用工程。创建新工程时点击“Create New Application”VS Code会弹出一个工程向导让你选择基础类型。这里我们选“Sampleapplication”然后会进入一个例程列表里面能看到samples目录下的大量官方demo。第一次使用的话强烈建议选择samples/basic/blinky这是最简单的LED闪烁例程代码逻辑少编译快适合用来验证整个工具链是否正常。选择完例程之后向导会要求选择目标开发板。这里需要你清楚自己的板子型号。我用的nRF52840 DK在列表中直接搜索nrf52840dk_nrf52840如果是nRF5340 DK就选nrf5340dk_nrf5340_cpuapp如果是nRF9160 DK就搜索nrf9160dk_nrf9160。选错板子会导致设备树不匹配编译时出现一堆底层定义缺失的错误。之后向导会要求填写工程名字和保存位置。我建议把工程放在SDK目录之外比如单独建一个workspace目录这样SDK源码如果需要整体删除重装不会影响你自己写的代码。这一点在日后维护多个项目时尤其重要把示例工程和SDK源码混在一起后续升级SDK版本容易误覆盖。3.3 编译、烧录与验证工程创建完成后VS Code右下方或者nRF Connect面板中会有“Build Configuration”之类的选项保持默认工程配置直接点击Build按钮即可。第一次编译需要一点时间因为要生成大量构建文件控制台里会滚动打印编译日志。看到Build completed或类似的成功提示说明工具链和SDK的配合没问题了。接下来是烧录。如果你的开发板是官方DK板载了J-Link调试器只需要用USB线连接开发板和电脑然后点击VS Code扩展中的“Build and Flash”工具会自动调用烧录程序把固件写入芯片。烧录成功后开发板上标记为LED0的LED就会开始闪烁到这一步NCS环境算是真正跑通了。如果你更喜欢纯命令行的操作方式也可以在VS Code的终端里执行west命令效果是一样的。前提是你已经在Toolchain Manager中打开过这个环境或者在完整路径下找到了工具链自带的终端。常用的三条命令是west build -b nrf52840dk_nrf52840来指定板子编译当前目录工程west flash来烧录以及west build -t menuconfig来打开图形化配置界面。关于west命令后边Linux章节还会更详细地展开。4. Linux环境命令行走安装NCS的完整流程4.1 安装系统依赖和nrfutil如果你使用的是Ubuntu或者Debian这类Linux发行版并不推荐手动去装各个开源组件然后自己组装NCS太容易出问题。Nordic官方提供了一套非常方便的命令行工具叫做nrfutil其中toolchain-manager子命令可以帮助我们一键安装NCS工具链。在开始之前先安装系统层面的依赖。我用的Ubuntu 22.04执行下面这条命令可以装齐大部分需要的东西sudo apt update sudo apt install --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 gcc-multilib g-multilib libsdl2-dev -y装完之后接着安装nrfutil。nrfutil的官方安装脚本很简单一般可以直接用如下方式curl -L https://developer.nordicsemi.com/.nordic/nrfutil/nrfutil -o nrfutil chmod x nrfutil sudo mv nrfutil /usr/local/bin/安装完成后先执行nrfutil version确认一下然后就可以使用toolchain-manager相关的命令了。这里注意一下nrfutil工具更新迭代比较快不同版本命令参数可能会略有一点差异建议装好后先执行nrfutil toolchain-manager --help看一眼各个子命令的用法。4.2 初始化SDK仓库和west工作区工具链安装完成后下一步是拉取SDK源码。我习惯把NCS相关的所有内容统一放在用户目录下的ncs文件夹里。先创建目录并进入mkdir -p ~/ncs cd ~/ncs然后执行west init。这里需要指定SDK的主仓库地址和分支。以NCS v2.6.0为例我使用的命令是west init -m https://github.com/nrfconnect/sdk-nrf.git --mr v2.6.0 v2.6.0 cd v2.6.0 west update解释一下这条命令的意思。-m参数指定manifest仓库地址也就是sdk-nrf--mr参数指定仓库的manifest revision也就是具体版本最后的v2.6.0是本地目录名。west init会把主仓库克隆下来形成一个west工作区的基础结构。紧接着west update会根据manifest文件里列出的所有子仓库把它们一起拉取到本地包括zephyr、mcuboot、nrfxlib等等这一步最耗时也会遇到网络问题具体排查办法我放在第5章里讲。在纯命令行的环境里需要确保工具链可用。如果说你直接用系统自带的gcc和cmake去编译NCS那几乎一定会失败因为这些工具的版本跟Zephyr的要求不匹配。正确的做法是用nrfutil进入到它安装好的工具链环境中。执行nrfutil toolchain-manager launch --shell会进入一个子shell在这个shell里PATH已经指向了nrfutil安装的工具链目录你使用的cmake、ninja、gcc、west都是预装好的正确版本。启动之后再执行west、cmake这些命令就不会有版本错乱的问题。如果你不想进入交互式shell也可以直接用nrfutil toolchain-manager launch -- west --version来一次性执行某个命令。4.3 配置烧录环境与设备权限编译环境就绪之后还要把烧录和调试的工具链搞定。Linux下推荐的组合是nrfjprog加J-Link驱动。nrfjprog是Nordic官方提供的命令行烧录工具打包在nRF Command Line Tools里下载对应Linux版本压缩包解压后把nrfjprog目录加到PATH。J-Link驱动则从SEGGER官网下载Linux版安装包安装后JLink驱动会在/opt/SEGGER/JLink目录下。烧录最常遇到的问题是没有权限访问USB设备。解决办法是把当前用户加到dialout组并配置udev规则。先执行sudo usermod -aG dialout $USER然后检查J-Link的安装目录下是否有udev规则文件。通常路径是/opt/SEGGER/JLink/99-jlink.rules如果有的话直接复制到系统udev目录并重载sudo cp /opt/SEGGER/JLink/99-jlink.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger配置完成后重新插拔一下开发板的USB线。通过nrfjprog --ids命令验证一下能看到一串设备编号说明驱动和权限都正常了。后续编译完工程直接在工程目录下执行nrfjprog --program build/zephyr/merged.hex --chiperase --reset就能烧录。如果你用的是较新的nrfutil也可以执行nrfutil device program --firmware build/zephyr/merged.hex用法上大同小异。5. 安装NCS最容易踩的坑与排查速查表5.1 版本漂移引发的编译错乱NCS最反直觉的一个特点是它的SDK和工具链并不是永远兼容的。新版本SDK可能要求更新的编译器老版本工具链也可能无法构建新SDK。Toolchain Manager在安装时就帮你锁定了版本匹配关系所以它不容易出问题。反而是在命令行模式下自己操作的人很容易出现“工具链更新了SDK还是老的”这种状态。我自己就踩过一次很深的坑在一次例行更新中我把nrfutil升级了又拉了一个新的NCS版本结果旧项目重新编译时出了一堆类似“undefined reference to ...”的错误。排查了半天才发现nrfutil的toolchain-manager把默认工具链切换到了新版本而旧的SDK工程还在用旧有的配置方式去调用两边版本不匹配。从那以后我学乖了每一个项目都在根目录的README里写明NCS版本号同时保证在Toolchain Manager或者nrfutil中使用的工具链版本和项目文档一致。如果多个项目需要并行建议用nrfutil toolchain-manager install分别安装不同版本的工具链再通过launch时指定的环境进入对应的目录。这样各干各的互不干扰。5.2 Python环境和依赖冲突命令行方式安装NCS时有一个非常典型的错误在系统Python里用pip装了west然后又用系统Python去执行west build结果编译时提示找不到虚拟环境里的包或者报“ModuleNotFoundError: No module named west”。这种情况几乎都是因为west所依赖的Python环境跟当前激活的Python环境不是同一个。用nrfutil工具链自带的Python环境是最稳妥的因为nrfutil在安装工具链时已经把west和Zephyr所需的Python依赖都处理好了我们只需要通过nrfutil toolchain-manager launch进入环境即可。如果你执意要用自己安装的Python环境那么安装完依赖后至少要在同一个终端里确认python -m west --version能正常输出版本再继续后续操作。还有一个小建议不要同时对系统Python、Anaconda、VS Code集成终端里的Python搞多个环境的混装。NCS构建系统的路径解析能力并没有那么强Python解释器一旦从不同路径切换往往会导致sys.path混乱表现出来就是一堆奇怪的导入错误。5.3 拉取SDK源码卡死或超时west update需要同时从GitHub拉取几十个仓库最直观的问题就是速度慢、超时、甚至中途断开。如果你发现某个仓库反复拉取失败首先可以尝试调整git的并发和缓冲区设置git config --global http.postBuffer 524288000 git config --global core.compression 0如果还是频繁失败再看一下网络环境。公司网络或者本地网络如果有可用的HTTP代理可以给git配上git config --global http.proxy地址端口。配好之后重新尝试west update。另外有一个很实用的技巧就是减少git拉取的提交历史。west update默认会把仓库的完整git历史拉下来但对我们普通开发来说历史记录绝大多数时候用不上反而白白消耗时间和磁盘。你可以在west update时加上--fetch-opt参数只拉取最新的分支提交west update --fetch-opt--depth1这个方式在仓库多、网络差的情况下效果非常明显。代价是后面切换分支或者查看历史会比较受限需要时可以单独在对应仓库里执行git fetch --unshallow恢复完整历史。如果你只是想快速把环境跑起来这个方案很值得一试。5.4 烧录失败与驱动识别问题编译通过之后烧录这一环也有一堆经典问题等着你。最常见的是nrfjprog报错“Could not connect to target”。这类报错往往不是软件配置问题而是芯片当前处于低功耗状态或者调试接口被占用。简单的解决方法是按住开发板上的复位键不放点击烧录看到烧录工具开始连接时立即松开复位键。这个操作利用的是芯片冷启动的窗口期成功率很高。还有一类问题是“No debug probe found”。如果刚装完J-Link驱动这个报错通常意味着电脑没有识别到调试探针。先检查USB线连接有些Micro USB线只能充电不能传数据换一根试试。然后确认J-Link驱动是否安装成功Linux下可以执行lsusb查看是否有SEGGER相关的设备信息。如果nrfjprog连上以后一直报“Error: Fault during programming”常见原因是芯片里的锁定位或者访问端口配置被改过了。这时候可以用nrfjprog --recover强制恢复芯片或者用nrfjprog --eraseall先擦除整个芯片再烧录。需要提醒的是擦除会清除芯片内所有数据量产前的开发阶段问题不大但有重要数据的时候一定要慎用。5.5 问题排查速查表为了方便你遇到问题时快速定位我把刚才提到的典型场景整理成表格报错或现象常见原因优先尝试的解决办法west init卡住不动网络原因导致GitHub连接不稳定配置git代理或http.postBuffer后重试west update时某个仓库反复失败仓库太大或网络波动用west update --fetch-opt--depth1降低数据量编译时提示No module named westPython环境混乱west所在环境不对通过nrfutil toolchain-manager launch进入正确环境CMake版本错误或不兼容使用了系统自带的较老cmake确认是否已进入NCS工具链shell检查cmake --version找不到目标板设备树文件选择的board名称与实际开发板不匹配在nRF Connect扩展中重新选择正确的board型号nrfjprog提示Could not connect芯片进入低功耗状态调试口被占用按住复位键再点烧录或使用nrfjprog --recovernrfjprog提示No debug probe foundJ-Link驱动未安装或USB线不可用重装J-Link驱动换数据线检查USB端口Linux下开发板串口打不开用户不在dialout组或无udev规则执行usermod -aG dialout并配置JLink的udev规则后注销重登编译成功后LED不闪烁烧录了错误固件或工程配置不对确认board和example选择正确重新编译烧录这个表里的问题大概率覆盖了从安装NCS到跑通第一个demo过程中90%以上的坑。遇到错误时先别急着换方案按这个表逐个排查基本都能解决。就我个人的使用习惯来说安装NCS最省心的方式还是Windows下用Toolchain Manager加VS Code扩展它把版本匹配、环境变量、Python依赖这些最容易出错的地方都帮你管起来了。Linux方案更适合那些需要把构建过程写进脚本、后面打算做自动化编译和发布的人。最后再分享一个小技巧我每新建一个产品级项目都会第一时间把NCS版本号记录在项目README里并且在west update完成之后执行west manifest --freeze把当前所有依赖仓库的精确版本提交信息锁定下来存储为一个west.yml文件。后续不管是自己换电脑还是团队其他成员加入只要用这份锁定的manifest执行west update就能在完全一致的代码版本上开展工作。这个习惯帮我避免了无数次“在我电脑上明明是好的”这种问题。NCS这套环境虽然初期安装有点门槛但一旦你理解了它背后的west工作区概念和版本管理思路后面管理再复杂的项目都会顺手很多。