前言
近期加入了多个星闪开发板交流群，和小伙伴们沟通时发现不少问题反复出现。为了提高大家的开发效率，特将高频问题汇总整理，方便各位开发者快速排查与解决。
一、ComX 打开失败，请检查串口是否被占用或不存在
提示信息如：
Com3 open fail, please check com is busy or not exist
应对策略：进入项目工程设置界面，重新指定可用的串口号。
二、CMake 安装中断
错误日志示例：
===== [cmake下载失败，请下载对应的whl文件至任意目录，在该目录下打开命令提示符（cmd）执行“pip install cmake-3.20.5-py2.py3-none-win_amd64.whl”即可，下载链接：https://files.pythonhosted.org/packages/65/7f/80cf681cd376834b442af8af48e6f17b4197d20b7255aa2f76d8d93a9e44/cmake-3.20.5-py2.py3-none-win_amd64.whl] =========== [pycparser下载失败，请下载对应的whl文件至任意目录，在该目录下打开命令提示符（cmd）执行“pip install pycparser-2.21-py2.py3-none-any.whl”即可，下载链接：https://files.pythonhosted.org/packages/62/d5/5f610ebe421e85889f2e55e33b7f9a6795bd982198517d912eb1c76e1a53/pycparser-2.21-py2.py3-none-any.whl] =========== [kconfiglib下载失败，请下载对应的whl文件至任意目录，在该目录下打开命令提示符（cmd）执行“pip install kconfiglib-14.1.0-py2.py3-none-any.whl”即可，下载链接：https://files.pythonhosted.org/packages/8a/f1/d98a89231e779b079b977590efcc31241249d959c8f1d4b5858cad69695ff9c/kconfiglib-14.1.0-py2.py3-none-any.whl] =========== [windowscurses下载失败，请下载对应的whl文件至任意目录，在该目录下打开命令提示符（cmd）执行“pip install windows_curses-2.3.3-cp311-cp311-win_amd64.whl”即可，下载链接：https://files.pythonhosted.org/packages/18/1b/e06eb41dad1c74f0d3124124218084f258f73a5e76c67112da0ba174162670f/windows_curses-2.3.3-cp311-cp311-win_amd64.whl] ============== [Python环境中的pip install异常,若添加后仍编译失败请关闭请关闭所有HiSpark Studio再打开重新执行编译] ======
解决方案参考：星闪开发入门教程之编译工具安装与烧录指南——详见文章第一部分第3小节
三、配置脚本语法异常
若 CMakeLists.txt 或其他构建脚本存在格式错误，可能导致编译流程中断：
Executing task: python \"e:\HiSparkStudio\HiSpark Studio\resources\app\extensions\huawei.cfbb-kconfig-0.0.1\configHandler\show_config.py\" \"./config.in ws63 acore ws63-liteos-app ./build/config/target_config/ws63/menuconfig/acore\" \"guiconfig\" Traceback (most recent call last): File "e:\HiSparkStudio\HiSpark Studio\resources\app\extensions\huawei.cfbb-kconfig-0.0.1\configHandler\show_config.py", line 64, in <module>show_kconfig(kconfig_path, show_kconfig_args, show_konfig_choice, None) File "e:\HiSparkStudio\HiSpark Studio\resources\app\extensions\huawei.cfbb-kconfig-0.0.1\configHandler\show_config.py", line 38, in show_kconfig kconf = Kconfig(filename=kconfig) ^^^^^^^^^^^^^^^^^^^^^^^^^ </module>
建议操作：逐行核查配置文件内容，确认无拼写、缩进或结构错误
四、路径太长引发构建失败
建议将源码存放于磁盘根目录下（例如 D:\project），避免深层嵌套路径带来的兼容性问题。
五、ninja 构建失败提示 subcommand failed
常见于编译阶段中断。排查方向如下：
- 核对报错命令中涉及的所有路径是否正确，在终端手动运行该命令验证可行性；
- 更新 ninja 工具：使用 pip 命令重新安装或升级
pip3 install ninja
之后重新触发编译流程。
六、OLED 显示字符混乱
针对型号为 ws63 的 OLED 屏幕，需采用阴码、逐行扫描、正向生成字模的方式。
具体处理方式可查阅：《星闪开发实战｜一篇文章搞定 OLED 显示》
七、Python 模块缺失问题（如 distutils）
报错信息如下：
Traceback (most recent call last): File "d:\fbb_ws63-master\src\build.py", line 38, in <module> from distutils.spawn import find_executableModuleNotFoundError: No module named 'distutils'</module>
修复建议：更换或降级安装 distutils 包版本。
详细步骤请参考：如何解决 ModuleNotFoundError: No module named ‘distutils’
八、SLE 连接返回错误码
略（保留原位置用于后续补充）
九、其他通用性问题汇总
包括但不限于：
- 内存泄漏
- 函数或变量未定义
- 编译参数配置不当
- 第三方库缺失
- 库文件路径错误
- 空指针访问
- 数组越界
- 多线程资源竞争或死锁等
典型表现可能是：
工具链安装不完整或配置不正确可能导致编译失败使用代码编辑器或IDE的语法高亮和错误提示功能，以及调试工具来定位并修复这些问题。仔细审查代码逻辑，确保所有条件、循环、函数调用等都正确无误硬件连接不正确或不稳定，以及硬件故障可能导致通信失败或数据错误清理不必要的文件或移动数据到其他磁盘上，以释放足够的空间有的时候要注意产品更新后引脚配置是否修改，避免做无用功。......
十、调试辅助软件推荐
以下是我日常开发中常用的调试工具：
总结
星闪开发过程中遇到的问题多种多样，涵盖环境搭建、代码质量、硬件连接及系统兼容等多个层面。建议先确认硬件连接正常后再聚焦软件问题。遇到报错时结合日志信息，在本文或相关文档中寻找对应解决方案，并善用调试工具精准定位。后续将持续收集新问题，欢迎留言或私信交流！
