CadQuery 本地运行环境：从代码到 STEP/STL 导出（V9C）¶

本页是 V9B（服务器端环境诊断）的后续。V9B 确认云端环境不能真实运行 CadQuery（OCCT 依赖不可用）。本页帮助读者在**自己的机器上**配置环境、运行代码、导出 STEP/STL。

A. 本页解决什么问题¶

背景回顾¶

V7/V8 已提供 6 个 CadQuery 代码示例（code/cadquery/*.py）
V9B 已完成云端运行诊断：Python 3.10 + Ubuntu 22.04，CadQuery 不可用
所有代码通过了 py_compile 语法检查，但**未真实生成模型**

本页提供什么¶

2 条本地环境路线（Python venv + Conda）
最小 smoke test 代码
运行 V7/V8 示例的推荐顺序
导出文件保存策略
导出后检查清单
8 条常见错误

目标¶

让读者可以在自己的机器上生成 STEP/STL，再回到 Mini-Lab：STEP 与 STL 格式对比实验做格式对比检查。

B. 为什么 py_compile 通过不等于 CadQuery 可运行¶

py_compile 只检查语法¶

python -m py_compile plate_with_hole.py 只验证：

Python 语法正确（无 SyntaxError）
缩进正确
import 语句存在

不能验证：

CadQuery 能正确生成几何
OCP（OpenCascade Python wrapper）可加载
STEP/STL exporters 正常工作
几何尺寸与设计一致

CadQuery 运行需要几何内核¶

CadQuery 依赖 OCP （OpenCascade Python wrapper），OCP 依赖 OCCT （OpenCascade Technology）C++ 库。这是一套庞大的几何引擎：

你的 Python 代码
    ↓
CadQuery（Python API）
    ↓
OCP（Python → C++ 桥接）
    ↓
OCCT（C++ 几何内核）
    ↓
STEP/STL 文件

任何一层缺失都会导致运行失败。

V9B 环境诊断结论¶

参考 CadQuery 真实运行与 STEP/STL 导出试点（V9B）（V9B 页面）：

Python 3.10.12 —— CadQuery 2.8 需要 Python 3.11+
CadQuery 2.3 支持 Python 3.10，但 OCP 在 PyPI mirror 不可用
pythonocc-core 也不可用
结论：本服务器不能跑 CadQuery，但读者本地可以

C. 推荐本地环境路线¶

路线 1：Python 3.11+ 虚拟环境¶

适合熟悉 Python 的读者。

# 1. 确认 Python 版本（需要 3.11+）
python3.11 --version
# 如果没有，从 python.org 或系统包管理器安装

# 2. 创建虚拟环境
python3.11 -m venv venv-cadquery
source venv-cadquery/bin/activate

# 3. 安装 CadQuery
pip install cadquery

# 4. 验证 import
python -c "import cadquery as cq; print(f'CadQuery {cq.__version__} OK')"

# 5. 运行 smoke test
python scripts/cadquery/smoke_test_cadquery.py

# 6. 运行项目示例
python code/cadquery/plate_with_hole.py

备注

如果 import cadquery 报 ModuleNotFoundError: No module named 'OCP'，说明 pip 未自动安装 OCP。此时建议改用**路线 2（Conda）**，因为 conda-forge 会自动处理 OCCT 二进制依赖。

路线 2：Conda / micromamba 环境¶

适合需要更稳定几何依赖的读者。推荐路线。

# 1. 安装 miniconda 或 micromamba
#    miniconda:
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

#    或 micromamba（更轻量）:
#    curl micro.mamba.pm/install.sh | bash

# 2. 创建 CadQuery 环境
conda create -n cadquery python=3.11
conda activate cadquery

# 3. 从 conda-forge 安装（自动处理 OCCT）
conda install -c conda-forge cadquery

# 4. 验证
python -c "import cadquery as cq; print(f'CadQuery {cq.__version__} OK')"

# 5. 运行 smoke test
python scripts/cadquery/smoke_test_cadquery.py

# 6. 运行项目示例
python code/cadquery/plate_with_hole.py

小技巧

conda-forge 的 CadQuery 包会自动安装 OCP 和 OCCT 二进制，不需要手动处理 C++ 依赖。这是最省心的路线。

环境配置示例文件¶

本仓库提供了 environment-cadquery.yml 示例文件：

conda env create -f environment-cadquery.yml
conda activate cadquery

备注

安装前请查看 CadQuery 官方安装说明或 PyPI 页面确认当前版本要求。

D. 最小 smoke test¶

以下是最小验证代码。也可以直接运行 scripts/cadquery/smoke_test_cadquery.py。

import cadquery as cq
import tempfile
import os

print(f"CadQuery version: {cq.__version__}")

# 创建一个 10x10x10 的 box
box = cq.Workplane("XY").box(10, 10, 10)
print(f"Box volume: {box.val().Volume()}")

# 导出 STEP
step_path = os.path.join(tempfile.gettempdir(), "smoke_test.step")
cq.exporters.export(box, step_path)
print(f"STEP exported: {os.path.getsize(step_path)} bytes")

# 导出 STL
stl_path = os.path.join(tempfile.gettempdir(), "smoke_test.stl")
cq.exporters.export(box, stl_path)
print(f"STL exported: {os.path.getsize(stl_path)} bytes")

print("Smoke test passed!")

预期输出：

CadQuery version: 2.X.X
Box volume: 1000.0
STEP exported: ~7000 bytes
STL exported: ~3000 bytes
Smoke test passed!

E. 运行本项目示例¶

运行方法¶

cd /path/to/CAD-CAM-Technology-docs
python code/cadquery/plate_with_hole.py

注意事项¶

先跑单零件，确认导出正常后再跑 assembly
如果 assembly 示例失败，先确认单零件导出正常
assembly 示例依赖更多几何内核能力（装配约束、干涉检查），可能需要更新版本
不要直接把教学导出文件用于真实机床或生产

F. 导出文件保存策略¶

建议目录结构¶

CAD-CAM-Technology-docs/
├── code/cadquery/          # 源代码
├── scripts/cadquery/       # 辅助脚本
└── local-exports/          # 本地导出（.gitignore 忽略）
    ├── plate_with_hole.step
    ├── plate_with_hole.stl
    ├── plate_advanced_features.step
    ├── plate_advanced_features.stl
    ├── bracket_capstone.step
    ├── bracket_capstone.stl
    ├── bracket_assembly.step
    └── bracket_nested_assembly.step

创建目录并运行¶

mkdir -p local-exports
python scripts/cadquery/run_plate_export.py

Git 策略¶

local-exports/ 已加入 .gitignore，默认不提交
小型教学文件（< 100KB）可手动检查后用 git add -f 精确加入
大型文件不建议提交仓库
参考资源包说明：assets/cadquery-exports/README.md

G. 导出后检查¶

检查清单¶

导出后检查项¶
#	检查项	方法	说明
1	文件是否生成	`ls -la local-exports/`	确认文件存在且大小 > 0
2	文件大小是否异常	`ls -lh`	STEP 通常几 KB～几十 KB；STL 几 KB～几 MB
3	STEP 能否在 CAD 查看器打开	FreeCAD / Online Viewer	打开后应显示完整几何
4	STL 能否在网格查看器打开	切片软件 / MeshLab	打开后应显示三角面片
5	单位是否一致	FreeCAD 测量工具	尺寸应为 mm（毫米）
6	孔和圆角是否保留	FreeCAD 测量	中心孔直径、倒角尺寸
7	STL 是否明显粗糙或破洞	视觉检查	面片数量太少 → 调整 tolerance
8	STEP vs STL 视觉对比	并排打开	几何应一致

自动化检查¶

使用 scripts/cadquery/verify_exports.py 自动检查文件格式：

python scripts/cadquery/verify_exports.py local-exports/*.step local-exports/*.stl

H. 常见错误¶

常见错误与解决方法¶
#	错误	解决方法	严重度
1	Python 版本不匹配（CadQuery 2.8 需要 3.11+）	升级 Python 或降级 CadQuery 到 2.3	⭐⭐⭐
2	cadquery 安装成功但 OCP 缺失	改用 conda-forge 安装（自动处理 OCCT）	⭐⭐⭐
3	`import cadquery` 报 ModuleNotFoundError	确认虚拟环境已激活，确认 pip install 成功	⭐⭐⭐
4	exporters 导出失败（PermissionError / 路径不存在）	确认输出目录存在：`mkdir -p local-exports`	⭐⭐
5	当前目录不对导致文件没生成	确认在仓库根目录运行，或用绝对路径	⭐⭐
6	输出路径不存在	创建 `local-exports/` 目录	⭐⭐
7	STEP/STL 文件为空或过小（< 100 bytes）	检查模型是否为空，检查 exporter 参数	⭐⭐
8	assembly 示例依赖更多几何内核能力	升级 CadQuery 和 OCP 到最新版	⭐⭐
9	把教学导出文件当成生产文件	教学文件不适合真实机床或生产环境	⭐⭐⭐

I. 相关页面¶

CadQuery 真实运行与 STEP/STL 导出试点（V9B） —— V9B 服务器端环境诊断
Python + CadQuery：用代码生成参数化零件 —— V7A 带孔板
CadQuery 进阶：圆角、倒角、阵列与支架变体 —— V7B 圆角/倒角
CadQuery 支架 Capstone：用代码生成完整支架 —— V7C 完整支架
CadQuery 学习路径：从入门到 Capstone 收口 —— V7D 学习路径
CadQuery Assembly 入门：从单零件到多零件装配体 —— V8A 装配体
CadQuery Assembly 学习路径：从多零件到装配检查 —— V8D 装配路径
Mini-Lab：STEP 与 STL 格式对比实验 —— STEP vs STL 格式对比
FreeCAD 导出 STEP/STL 检查清单 —— FreeCAD 导出检查

J. 相关脚本¶

scripts/cadquery/smoke_test_cadquery.py —— 最小环境验证
scripts/cadquery/run_plate_export.py —— 导出 plate_with_hole
scripts/cadquery/verify_exports.py —— 验证导出文件格式
scripts/cadquery/README.md —— 脚本使用说明
environment-cadquery.yml —— Conda 环境配置示例

CadQuery 本地运行环境：从代码到 STEP/STL 导出（V9C）¶

A. 本页解决什么问题¶

背景回顾¶

本页提供什么¶

目标¶

B. 为什么 py_compile 通过不等于 CadQuery 可运行¶

py_compile 只检查语法¶

CadQuery 运行需要几何内核¶

V9B 环境诊断结论¶

C. 推荐本地环境路线¶

路线 1：Python 3.11+ 虚拟环境¶

路线 2：Conda / micromamba 环境¶

环境配置示例文件¶

D. 最小 smoke test¶

E. 运行本项目示例¶

推荐运行顺序¶

运行方法¶

注意事项¶

F. 导出文件保存策略¶

建议目录结构¶

创建目录并运行¶

Git 策略¶

G. 导出后检查¶

检查清单¶

相关页面¶

自动化检查¶

H. 常见错误¶

I. 相关页面¶

J. 相关脚本¶