遇到问题时怎么排查
先标记失败阶段：环境 → 配置 → 编译 → 烧录 → 启动 → 外设行为。每次只改一个变量，并保存原始错误文本。
| 现象 | 首先检查 | 后续动作 |
|---|---|---|
west: command not found | Python 虚拟环境是否激活 | source ~/Projects/zephyr-workspace/.venv/bin/activate |
找不到 west build 扩展 | 当前目录是不是 west 工作区 | 进入工作区；检查 west update 是否完整成功 |
| 找不到 SDK / compiler | SDK 安装是否完成 | 核对实际路径、架构、CMake 注册与环境变量 |
| blobs 缺失 | hal_espressif 下载是否完成 | 在正确工作区执行 west blobs fetch hal_espressif |
| 板卡名无效 | 板卡系列、完整目标及 Zephyr 版本 | 查当前版本 board.yml，避免照搬其他系列名称 |
led0 未定义 | LED 别名及 overlay 是否加载 | 查看最终 zephyr.dts 与编译器首个错误 |
| 串口 permission denied | 设备属组与当前用户组 | ls -l 检查节点，id 检查当前组；按系统策略配置后重新登录 |
| 无法进入下载模式 | 数据线、串口占用、BOOT / EN 时序 | 关闭占用端口的监视器，按板卡手册进入下载模式 |
| 烧录成功但无输出 | 正确串口、波特率、复位与引导方式 | 先开启监视器再复位，回到最小 Hello World |
| LED 不亮 | 原理图、极性、限流电阻及 GPIO | 核对实际接线与最终设备树 |
不要用 chmod 777 或一直以 root 运行开发工具来掩盖串口权限问题。先识别当前发行版和设备实际权限。
有效的问题记录
目标：
主机系统及架构：
板卡与模组：
Zephyr 标签 / commit：
SDK / west / Python 版本：
当前工作目录：
完整命令：
第一条错误及上下文：
已尝试的单项修改：
修改后的结果：
若更换板卡、源码版本或 overlay，使用独立构建目录，或对明确指定的构建目录执行 pristine build。不要为了修复构建缓存而删除整个工作区。
hidapi 安装失败：开发库与编译器
本机 Fedora / Python 3.14 安装 Zephyr v4.2.0 的完整 requirements 时，实际连续遇到了两个错误。后一个不是前一个重复出现，而是源码构建继续到下一阶段后暴露的问题。
| 阶段 | 原始错误 | 原因与处理 |
|---|---|---|
| 获取构建要求 | pkg-config package 'libusb-1.0 >= 1.0.9' not found | 缺少 libusb 开发文件；安装 libusb1-devel，同时补齐 libudev 的 systemd-devel |
| 编译 wheel | error: [Errno 2] No such file or directory: 'gcc' | 缺少主机 C 编译器；安装 gcc，并完整检查环境依赖 |
| west 打印失败命令 | TypeError: expected string object, got 'PosixPath' | 报错包装中的次生错误，应查看更前面的 pip 日志 |
一次检查完整前置条件
sudo dnf install gcc gcc-c++ make python3-devel libusb1-devel systemd-devel pkgconf-pkg-config
rpm -q gcc gcc-c++ make python3-devel libusb1-devel systemd-devel pkgconf-pkg-config
gcc --version
pkg-config --modversion libusb-1.0 libudev
不要在任一检查失败时继续安装 Python 包。系统开发包需要本机 sudo 权限；pip 在虚拟环境内运行，不使用 sudo。
仅重试失败的安装步骤
source ~/Projects/zephyr-workspace/.venv/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
python -c "import sys; print(sys.executable); print(sys.version)"
west packages pip --install
不需要重新 west init、删除工作区或重新下载源码。
安装完成的判据
先确认 west packages pip --install 以退出码 0 结束，然后验证：
python -m pip check
python -c "import hid; print('hidapi import OK')"
pip check 只验证已安装包之间的依赖关系；空环境或未完整安装的环境也可能显示没有依赖冲突。因此不能只看这一条命令就宣称安装完成。
获取没有 west 次生错误的 pip 日志
本次工作区的 west packages pip 列出 Zephyr 和 MCUboot 两份 requirements。在 Zephyr 源码目录中可直接运行：
python -m pip install -r scripts/requirements.txt \
-r ../bootloader/mcuboot/zephyr/requirements.txt
模块发生变化时以 west packages pip 的实际输出为准。失败后保留第一条真实错误及其上下文，不要只截取最末尾的 west traceback。
Python 版本与验证范围
本次 Python 3.14 下选择了 hidapi 源码包；已复现的直接失败原因是系统开发库和 GCC 缺失。Python 3.12 可以作为新环境的候选，但更换解释器不能替代完整环境检查，也不保证所有依赖都提供 wheel。
本次另建的 Python 3.12.14 环境 .venv-py312 已通过完整依赖安装、pip check 和 import hid 检查；原 .venv 保留。使用方式见工作区说明。固件编译和实板运行尚未验证。
参考：hidapi 上游构建依赖。
冻结清单提示 canopennode 未克隆
RuntimeError: cannot freeze; project canopennode is uncloned
本机检查确认它属于未启用的 optional 组，所有启用项目均已克隆。只记录当前启用项目即可：
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
west manifest --freeze --active-only -o ../west-manifest-frozen.yml
本机已执行成功并解析 YAML，快照包含 57 个项目。不要为了冻结当前学习环境而下载所有可选模块。若确实要使用 CANopenNode，再单独启用、下载和配置它。
原命令使用 > 时，shell 会提前截空目标文件，即使 west 随后失败也可能留下零字节文件；应重新生成成功的快照。