遇到问题时怎么排查

先标记失败阶段：环境 → 配置 → 编译 → 烧录 → 启动 → 外设行为。每次只改一个变量，并保存原始错误文本。

现象	首先检查	后续动作
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。不要为了修复构建缓存而删除整个工作区。