第16章：常见问题、排错与最佳实践

1. F5 正常但 F6 失败

可能原因：

• 模型存在非流形或自交。
• 差集切除体与主体共面。
• 多边形路径未闭合或顺序错误。
• polyhedron 面方向错误。
• 导入 STL 本身有问题。
• 几何过于复杂导致内存或时间不足。

处理方法：降低模型复杂度，隔离模块，添加 epsilon 余量，检查导入网格，先二维验证，再逐步恢复。

2. 导出 STL 尺寸不对

常见原因是单位误解。OpenSCAD 没有内置单位，STL 也没有明确单位。切片软件通常按毫米解释。若外部导入来自英寸或其他比例，需要显式 scale，并在文档中说明。

3. 圆不够圆或模型太慢

圆不够圆，提高 $fn、降低 $fa 或 $fs。模型太慢则降低曲面分辨率、减少布尔对象、避免大规模 minkowski。最佳实践是预览和导出使用不同质量参数。

4. 变量行为不符合直觉

OpenSCAD 不是传统命令式语言。不要写依赖逐步赋值累加的逻辑。使用函数、列表推导、递归和明确派生变量。把“改变状态”的想法转换成“表达结果”的想法。

5. 孔位对不上

应把孔位定义为函数或共享列表，底壳、盖板和装配都引用同一来源。不要在多个模块中手写相同坐标。孔位还要考虑装配间隙、打印误差和螺丝标准。

6. include 和 use 混乱

建议库文件顶层不生成几何，配置文件只放变量，零件文件只放模块。需要共享变量时用 include，只想调用模块/函数时用 use。项目越大，越要减少隐式全局依赖。

7. 布尔后出现奇怪裂缝

检查是否有共面、零厚度、仅边接触或仅点接触。让实体之间有微小重叠，让切除体穿透主体。对导入网格先修复再参与布尔。

8. 文字在别人电脑上变了

字体依赖系统环境。团队协作时明确字体名称和安装方式，或将文字轮廓导出为固定 SVG/DXF 再导入。用于工程标识时，还要考虑字体最小笔画宽度是否可打印。

9. 文件越来越难维护

当单文件过长时，应拆分：

• config.scad：参数。
• lib/*.scad：通用函数和模块。
• parts/*.scad：零件。
• main.scad：装配和导出入口。

同时建立命名规范、坐标约定和导出脚本。

10. 3D 打印失败

OpenSCAD 只负责模型几何，不保证打印成功。检查：

• 壁厚是否足够。
• 悬垂是否需要支撑。
• 孔径是否补偿。
• 大平面是否翘曲。
• 卡扣是否有弹性空间。
• 螺丝柱是否有加强筋。
• 模型是否闭合且法线正确。

11. 最佳实践总结

• 文件顶部写单位、版本和公开参数。
• 模块只做一件事。
• 坐标原点和朝向必须明确。
• 重复结构用循环，重复公式用函数。
• 布尔切除体略微穿透主体。
• 预览低精度，导出高精度。
• 不把调试参考对象导出到最终模型。
• 对外发布时提供参数说明和导出命令。
• 对源码贡献保持小步、可测试、可复现。

12. 继续学习资源

• OpenSCAD 官方网站：https://www.openscad.org/
• OpenSCAD 官方仓库：https://github.com/openscad/openscad
• OpenSCAD 用户手册：https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
• 官方 examples 目录：基础、函数、参数化和高级示例。
• 社区库：MCAD、BOSL2 等。

学习 OpenSCAD 的最佳方式是不断把真实小需求变成参数化模型：做一个支架、一个盒子、一个夹具、一个转接板，然后逐步抽象出自己的零件库。