01 环境篇：PC 开发环境、Python、WSL2、Keil 与网络的那些坑
·
01 环境篇：PC 开发环境、Python、WSL2、Keil 与网络的那些坑
系列第 2 篇。这一篇全是"还没碰到板子就先卡住"的坑：Windows 上的编码、Python 环境、WSL2 训练环境、Keil/STM32 工具链、网络问题。共 30+ 个真实事件，按主题分组，每条含现象/根因/解决/教训。
一、编码与文本（最容易被忽略的隐形坑）
1. Windows 记事本写的 .md 文件，VS Code 打开全是乱码（07-17）
- 现象：用记事本写了踩坑记录，改成
.md后 VS Code 打开全是乱码；cat出来也乱，iconv按 GBK 解码才正常。 - 根因：Windows 记事本默认按 ANSI/GBK 编码保存中文，VS Code 默认按 UTF-8 打开。
- 解决：VS Code 右下角"通过编码重新打开"选 GBK → 再"通过编码保存"选 UTF-8。
- 教训：所有代码和文档统一 UTF-8；直接用 VS Code 写，别用记事本。（另：当时还把"踩坑记录.md"建成了文件夹而不是文件——注意别建错类型。）
2. Windows 终端（GBK）打印 ✓ 等 Unicode 字符直接崩溃（07-28）
- 现象：脚本输出
✓等特殊符号时报 Unicode 编码错误。 - 根因：Windows 终端默认 GBK 编码，不认部分 Unicode 字符。
- 解决：脚本输出全部换 ASCII（如
[OK]）。
3. cv2.imwrite 中文路径静默失败：打印"已保存"但文件不存在（07-29）
- 现象：按空格后控制台打印"已保存"，但文件夹是空的；
cv2.imwrite返回False且不抛异常。 - 根因：Python 3.8 + OpenCV 的
cv2.imwrite底层是 C 函数，路径含中文时编码转换失败，静默返回 False。 - 解决：目录名改纯英文（
steel_dataset）；备选方案是cv2.imencode('.jpg', frame)+ 手动写文件。 - 教训：所有路径坚持英文。嵌入式+Windows 双端开发，中文路径是隐形炸弹。
二、Python 环境（Windows 端）
4. 系统根本没装 Python，python/pip 命令被 Microsoft Store 占位符劫持（07-22、07-28 重复出现）
- 现象：
python报Python was not found; run without arguments to install from the Microsoft Store；pip: command not found。 - 根因：
python.exe/python3.exe是商店的 App 执行别名（占位符），本机没装真 Python。 - 解决：官网下载 Python 3.8.10 安装；在"设置→应用→应用执行别名"把占位符重命名成
.bak禁用；Python 目录加入系统 PATH。
5. setx 加了 PATH，Git Bash 里 python 还是 command not found（07-28）
- 根因：Git Bash 有一套自己的 PATH 构建逻辑，不直接继承 Windows 用户 PATH。
- 解决：在
~/.bashrc里显式追加 Python 路径（export PATH="$PATH:/c/Users/Xiaodaidai/AppData/Local/Programs/Python/Python38"）。
6. 多 Python 并存：uv 的 3.14 没装 opencv，跑脚本报 No module named 'cv2'（07-30、07-31 重复）
- 现象：
tune_detector.py第一行import cv2就 ModuleNotFoundError；电脑上明明装了 opencv。 - 根因：
uv托管的 Python（cpython-3.14）是全新环境，没装任何包；系统 Python 3.8 才装好全部依赖。 - 解决：用完整路径
C:/Users/.../Python38/python.exe运行，或alias python=...。 - 教训：先确认解释器再跑脚本。多环境并存时一律用完整路径。
7. Windows 下 OpenCV 摄像头打不开 / 默认后端不兼容（07-28）
- 现象：
cv2.VideoCapture(0)无画面。 - 解决：显式指定后端
cv2.VideoCapture(0, cv2.CAP_DSHOW)（后来这个 USB 摄像头又变成 DSHOW 偏绿、要 MSMF，详见视觉篇）。
8. Windows 下摄像头索引混乱：0=手机、1=电脑内置、2=USB（07-31）
- 现象：
VideoCapture(1)打开的是电脑自带摄像头，不是 USB 摄像头。 - 根因：Windows 按系统枚举顺序分配索引，不固定。
- 解决：写个小脚本遍历 0~N 打印每路画面确认，再写死正确索引。
三、WSL2 训练环境（YOLOv5 训练 + RKNN 转换）
9. WSL2 apt 连不上官方源（07-22、07-23）
- 现象：
Failed to fetch http://archive.ubuntu.com/...，apt update 失败。 - 解决：换阿里云镜像：
sudo sed -i 's|http://archive.ubuntu.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list sudo sed -i 's|http://security.ubuntu.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list sudo apt update - 教训：国内网络环境下，任何官方源先换成阿里云/中科大，别死磕。
10. python3.9-pip 找不到包（07-22）
- 根因：python3.9-pip 不在 Ubuntu 20.04 默认仓库。
- 解决：deadsnakes PPA 装 Python 3.9 + 官方引导脚本装 pip：
sudo add-apt-repository -y ppa:deadsnakes/ppa sudo apt install -y python3.9 python3.9-distutils curl -sS https://bootstrap.pypa.io/pip/3.9/get-pip.py | python3.9
11. get-pip.py 报"This script does not work on Python 3.9"（07-22）
- 根因：新版 get-pip.py 要求 Python ≥ 3.10。
- 解决：用 3.9 专用链接
https://bootstrap.pypa.io/pip/3.9/get-pip.py（见上一条）。
12. pip 装到了 ~/.local/bin 不在 PATH（07-22）
- 解决：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc。
13. typing-extensions requires a different Python: 3.8.10 not in '>=3.9'（07-22）
- 根因：Python 3.8 太老，新库要求 ≥3.9。
- 解决：升级到 Python 3.9（同坑 10）。
14. rknn-toolkit2 强制把 torch 从 2.5.1 降级到 2.4.0（07-22）
- 现象：装 rknn-toolkit2 时 torch 2.5.1 被强制降级（740MB 白下了），随后
torchvision 0.20 与 torch 2.4 不兼容。 - 根因：rknn-toolkit2 要求
torch ≤ 2.4.0。 - 解决：
pip install torchvision==0.19。 - 教训：先查版本约束再装大包，避免重复下载。
15. ONNX 1.19 与 rknn-toolkit2 2.3.2 不兼容：module 'onnx' has no attribute 'mapping'（07-23）
- 解决：
pip install onnx==1.16.2。
16. quantized_dtype='asymmetric_quantized-u8' 报无效（07-23）
- 根因：rknn-toolkit2 2.3.2 的
rknn.config()不接受旧量化类型名。 - 解决：改用新 API 名
w8a8（最终正确值是asymmetric_quantized-8，见系统篇 RKNN 主坑）。
17. 训练启动失败：triton / importlib-metadata 报错（07-23）
- 根因：ultralytics 依赖的 importlib-metadata 版本不满足。
- 解决：
pip install 'importlib-metadata<5.0'，setuptools 降到 <75。
18. labelImg 在 WSL2 无法启动：qt.qpa.plugin: Could not load the Qt platform plugin 'xcb'（07-23）
- 排查：装了 libxcb-xinerama0 / libxcb-cursor0 仍失败。
- 解决：弃用 labelImg，改浏览器版 MakeSense.ai（零安装，导出 YOLO 格式）。
19. onnxsim 安装失败：Could not find "cmake" executable（07-24）
- 解决：先
apt install cmake再装 onnxsim（装完提示把~/.local/bin加进 PATH）。
20. bash: unzip: command not found（07-23）
- 解决：WSL 里
apt install unzip，或 Windows 端解压后 WSL 读取。
21. WSL 里文件拷不进 Windows / scp 跨文件系统失败（07-25，折腾 20 分钟）
- 现象：Windows 侧
scp "C:/Users/.../model.rknn"报No such file or directory；\wsl.localhost\...、Copy-Item全失败。 - 根因：Windows 进程看不见 WSL 的 ext4 文件系统，不能直接跨文件系统操作。
- 解决：先在 WSL 里
cp到/mnt/c/Users/Xiaodaidai/Desktop/，再从 Windows 侧 scp 到板子（这条通路以后固定使用）。
22. WSL2 NAT 模式下直连板子 scp 不通（07-24 反复）
- 现象：WSL 里 scp 到板子卡住/超时；base64 分块、busybox
base64报输入无效、split: cannot open连环失败。 - 解决：文件先拷到 Windows 可访问路径，再用 Windows 的 scp/ssh 传；板端解码用 Python
base64.b64decode代替 busybox。
四、Windows 开发工具（Keil / STM32 / 其他 IDE）
23. Keil 双击 .pack 文件报 command line error: unknown option（07-20）
- 根因：Windows 文件关联把 .pack 传给 Keil 的参数格式不对。
- 解决：别双击，打开 Keil → Pack Installer → File → Import Pack 手动导入；或命令行
"C:\Keil_v5\UV4\PackUnzip.exe" install xxx.pack。导入几百 MB 属正常。
24. Keil Pack Installer 满屏红字（.pdsc Unrecognized file format）（07-20）
- 根因：Pack Installer 自动联网拉取其他厂商（Microchip/NXP）包索引失败 +
.Web\缓存 .pdsc 损坏。 - 解决：这些和 TI MSPM0 无关，Devices 里能搜到 MSPM0G3507 就是装好了，红字可忽略；想消除就删
.Web缓存重建。
25. Keil 编译报 L6047U: image size (40080 bytes) exceeds the maximum allowed（07-20）
- 根因：Keil 是 Lite/试用版，32KB 代码大小限制。
- 解决：申请免费 MDK Community License（keil.com/license）解除限制；或
-Os压缩代码、关掉 printf/未用组件；或换 TI CCS / GCC。
26. CubeMX 新建工程一直卡在 “Connecting to HTTP Server”（07-26）
- 根因：ST 服务器国内访问慢/被墙，下不了芯片包 crdb.zip。
- 解决：
Help → Updater Settings关启动检查更新；或离线导入固件包（官网/GitHub 下载 zip →Manage embedded software packages → From Local...）；Repository 目录不存在时手动创建C:\Users\<用户名>\STM32Cube\Repository\。
27. STM32 头文件报 unknown type name 'uint8_t'（07-26）
- 根因：
uint8_t在<stdint.h>中，独立编译的 .h 文件没包含它。 - 解决：头文件顶部加
#include <stdint.h>。
28. ST-Link 下载系列坑（07-25、07-26）
- 现象：
No Target Connected→Connect Error→ 能下载但程序没反应；升级固件报is not in the DFU mode。 - 解决：
- 拔插 USB、降低 SWD 频率（4MHz→1MHz）；
- 按住板子 Reset 不放再点下载（低电平复位绕过锁死）；
- 勾选 “Reset and Run”，下载后按复位键运行；
- DFU 模式：拔掉 USB 和 SWD 线重插，不行短接 BOOT/3.3V；只要能烧录，点 No 不升级也不影响。
29. VS Code 里 Keil Assistant 找不到图标 / Rebuild 报 no target（07-26）
- 解决：settings.json 配编译路径：
或干脆 VS Code 只写代码、Keil 负责编译。"keil.ARMCompiler5.Path": "C:\\Keil_v5\\ARM\\ARMCC", "keil.ARMCompiler6.Path": "C:\\Keil_v5\\ARM\\ARMCLANG"
30. VS Code 改 ~/.ssh/config 提示权限不足（07-16）
- 解决：
icacls C:\Users\Xiaodaidai\.ssh\config /grant Xiaodaidai:F（注意 Git Bash 下/grant会被路径转换，用MSYS_NO_PATHCONV=1或 CMD 执行）。
31. PowerShell 跑 .\adb.exe shell 报错 / adb 不在 PATH（07-16）
- 根因：PowerShell 中
.是 dot-source 语法；adb 没加 PATH。 - 解决：切 Git Bash 用
./adb.exe shell，或把 adb 目录加进系统 PATH。
32. Trae IDE 登录失败 “Network connection failed”（07-22）
- 根因：校园网 DNS（
dns3.gdut.edu.cn）屏蔽了 Trae 海外认证子域名。 - 解决：换公共 DNS（114.114.114.114 / 223.5.5.5），登录时开代理，或下载国内版。
33. PowerShell 执行策略禁止运行 claude.ps1（07-22，重复 2 次）
- 现象：VSCode 终端输入
claude报"禁止运行脚本"（PSSecurityException），Git Bash 正常。 - 解决：管理员 PowerShell 执行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser；或 VSCode 默认终端改 Git Bash。
五、网络与下载
34. GitHub 443 端口被防火墙阻断，git clone 全部超时（07-15）
- 现象：
ping github.com通（93ms），但git clone https://...全部Failed to connect to github.com:443；WebFetch 也被拦。 - 解决：① 配代理
git config --global http.proxy http://127.0.0.1:<端口>；② 浏览器下载仓库 zip 手动解压；③ 用 Gitee 镜像。
35. git clone 超时留下残缺目录，重试报"目录已存在"（07-13）
- 解决：先删残留目录再 clone。教训：任何"重试前先清理"。
36. API 连接被拒：Claude Code 走 DeepSeek 网关时 ConnectionRefused（07-14、07-15）
- 现象：对话直接失败
API Error: Unable to connect to API。 - 根因：DeepSeek API 网关当时不可达（临时网络故障）。
- 处理：多轮重试仍失败就换网络/时段，别在同一会话里死磕。
37. WebFetch 报 Unable to verify if domain is safe to fetch（07-14、07-15）
- 根因：当前网络环境过不了域名安全校验。
- 解决：换能直连的渠道（GitHub 网页、镜像站）。
38. npx skills add 装 skill 失败 / npm 包 E404（07-14）
- 现象：
firmware-codegen-skill克隆卡死，npm i firmware-codegen-skill报 E404 Not Found。 - 根因：GitHub 时通时不通 + 该 skill 根本不是 npm 包名。
- 教训：网络受限优先 npm/Gitee 源，装前先确认包名。
39. cn-skills-cli 在 Windows 崩溃：EPERM + node 断言失败（07-15）
- 现象：npm 装包
EPERM: operation not permitted, rmdir node_modules；运行时Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)Exit 127。 - 解决：放弃该工具，换别的方式装（Git 代理 + 手动解压）。
六、Windows 系统杂项
41. 反复弹"本地安全机构保护 / 此模块被阻止加载"（事件 ID 3033）（07-17）
- 根因：Multisim/NI 的
nimdnsNSP.dll试图注入lsass.exe，无微软签名被 LSA 保护拦截（NI 知名老问题）。 - 解决：
msiexec /x卸载NI mDNS Responder 17.0+ MAX Remote Configuration 组件，重启后消失。
42. 桌面莫名出现"新建文件夹"含 .omc、.claude、skills-lock.json（07-17）
- 根因：某次 AI 工具会话把该文件夹当项目目录运行，遗留工具配置。
- 解决：确认无用户数据后整体删除。
43. 删除文件夹报 “Device or resource busy”（07-13）
- 根因：VS Code/资源管理器占用（终端当前目录、远程连接）。
- 解决：关占用程序后删除，或资源管理器右键删除。
小结：环境篇避坑清单
- 全英文路径、UTF-8 编码——两个隐形炸弹，先立规矩。
- 多 Python 并存：跑脚本前
which python/ 用完整路径，别赌默认解释器。 - 先查版本约束再装包（rknn-toolkit2 ↔ torch ↔ onnx 的版本锁死）。
- 国内网络：镜像源、代理、zip 手动下载，三选一。
- Keil 32KB 限制是 Lite 版功能限制，不是代码问题。
智能硬件社区聚焦AI智能硬件技术生态，汇聚嵌入式AI、物联网硬件开发者，打造交流分享平台，同步全国赛事资讯、开展 OPC 核心人才招募，助力技术落地与开发者成长。
更多推荐
3
0- 0
已为社区贡献1条内容
所有评论(0)