CadQuery 参数化 CAD 建模库本地部署指南

一、项目介绍

CadQuery 是一个用 Python 构建参数化 3D CAD 模型的开源库。它的设计理念是：用简短、贴近自然语言的脚本描述物体形状，就能生成高质量的 CAD 模型。你可以写一段脚本，通过修改参数批量生成不同尺寸、不同形状的零件，非常适合工程自动化、科学计算与服务器端建模。

与传统 CAD 软件依靠鼠标拖拽不同，CadQuery 以纯 Python 代码为模型格式，可被版本管理、可被 Web 浏览器直接执行与修改。它底层基于 OpenCASCADE（通过 OCP 绑定），支持倒角、曲线拉伸、参数曲线、放样等高级建模能力，并可输出 STEP、DXF、STL、VRML、AMF、3MF 等无损或交换格式。

这种"代码即模型"的思路，把制造业长期依赖手工制图的流程变成了可自动化、可复用的程序。对软件工程师来说，不需要学习一套全新的 CAD 交互语言，用熟悉的 Python 函数就能完成三维建模，门槛大幅降低。

CadQuery 还提供了官方 GUI 编辑器 CQ-editor（带调试器与堆栈检查器），并支持在 JupyterLab 中直接可视化模型。

为什么要用代码做 CAD

传统 CAD 软件（如 SolidWorks、AutoCAD）依赖鼠标点选与菜单操作，模型是二进制或私有格式，难以进入版本管理流程。当你需要"批量生成一百个不同孔径的法兰"或"根据实验参数实时调整零件形状"时，手工拖拽效率极低且容易出错。CadQuery 把建模过程变成一段 Python 脚本，意味着模型可以像代码一样被 git 追踪、被 code review、在 CI 中自动渲染对比，也能被后端服务调用，根据用户输入动态产出 STEP 文件用于 3D 打印或 CNC 加工。

这种"程序化建模"思路在硬件自动化、参数化设计生成、计算制造领域尤其有价值。你可以把设计规则写进函数，让代码替你执行重复性的几何构造工作；也可以在 Jupyter Notebook 里边改参数边看模型变化，形成"设计即代码"的闭环。对 Python 工程师而言，不需要额外学习一套专有的 CAD 交互语言，用熟悉的函数调用就能完成 3D 建模，学习曲线相对平缓。

值得一提的是它的输出格式选择。STEP 是工业界通用的无损交换格式，几乎所有 CAD 软件都能打开，这意味着你用 CadQuery 生成的零件可以无缝进入下游加工流程；STL 与 3MF 则是 3D 打印的标准格式。这种"一次建模、多格式导出"的能力，让它既能服务精密机械设计，也能服务快速原型制作。对做硬件原型、自动化装置、定制支架的开发者来说，它把"从想法到可打印文件"的距离缩短到了几行代码。

二、官方信息

三、项目结构与核心特性

核心特性：

• 脚本化建模：用接近自然语言的 Python 描述物体，如 box(1,1,1)、fillet(...)。
• 参数化：一个脚本通过参数变化可生成一族零件。
• 高质量输出：支持 STEP、DXF 等无损格式，以及 STL、3MF 等 3D 打印格式。
• 高级建模：倒角、曲线拉伸、参数曲线、放样、嵌套装配体。
• 内置可视化：基于 trame 与 vtk，无需 GUI 也能查看模型。
• 多安装方式：conda/mamba/micromamba/pixi 或 pip，官方更推荐 conda。

多种安装方式覆盖了不同偏好的用户：习惯 conda 的用 mamba 快速解依赖，纯 pip 党也能直接装。官方推荐 conda 是因为 OpenCASCADE 的系统依赖较多，conda 能一次性配齐，省去手动编译的麻烦。

四、环境与版本要求

注意：Ubuntu 18.04 等较老发行版不被 pip wheel 支持；pip 安装失败时建议改用 conda。

这里的 Python 版本区间（3.9 到 3.12）是硬性约束，因为底层 OCP 绑定是按特定 Python 版本预编译的，超出范围没有对应 wheel。很多人用 3.13 装会失败，就是这个原因。如果你已经在用更新的 Python，最省事的办法是用 conda 单独建一个 3.11 环境专门跑 CadQuery。官方更推荐 conda，因为它能一次性把 OpenCASCADE 的系统依赖配齐，省去自己装库的麻烦。

五、本地部署步骤

方式一：conda 安装（官方推荐）

# 创建环境
conda create -n cadquery
conda activate cadquery

# 安装最新发布版（推荐 mamba 以加快速度）
mamba install -c conda-forge cadquery

# 或安装开发版
mamba install -c conda-forge -c cadquery cadquery=master

方式二：pip 安装

python3 -m pip install --upgrade pip
pip install cadquery

从 GitHub 安装最新代码：

pip install git+https://github.com/CadQuery/cadquery.git

方式三：容器快速体验

# apptainer
apptainer run oras://ghcr.io/cadquery/cadquery-apptainer:master \
  ipython -i -c "from cadquery.func import *; from cadquery.vis import show; show(box(1,1,1))"

# 或 podman/docker
podman run -i -v /tmp:/tmp -e DISPLAY=$DISPLAY \
  --userns=keep-id --user "$(id -u):$(id -g)" --device /dev/dri \
  -t ghcr.io/cadquery/cadquery-docker:master \
  ipython -i -c "from cadquery.func import *; from cadquery.vis import show; show(box(1,1,1))"

验证安装

python3 -c "import cadquery as cq; b = cq.Workplane('XY').box(1,1,1); print(b.val().Volume())"

输出 1.0（单位立方）即说明安装成功。

这一步虽然简单，却同时验证了三件事：OCP 内核能否正常加载、Python 绑定是否可用、能否正确创建一个三维实体并计算体积。如果这一步报错，通常是 OCP 的系统依赖没装好或 Python 版本不在支持范围内，这时应回到安装步骤改用 conda，而不是继续往下调试模型代码——内核层没通，后面所有建模都会失败。建议在虚拟环境里把这个验证命令存成一个脚本，换环境时先跑一遍。

（可选）安装 CQ-editor GUI

mamba install -c cadquery -c conda-forge cq-editor=master

启动后可在图形界面里编辑脚本、单步调试、查看建模堆栈并导出 STEP/STL。

第一次建模建议从最简单的立方体开始，逐步叠加倒角、打孔等操作，观察脚本与模型的对应关系。理解了脚本如何描述形状，再做复杂零件就有抓手。

六、API 用法与示例

1. 内置可视化（trame/vtk）

from cadquery.func import box, fillet
from cadquery.vis import show

b = box(1, 1, 1)
show(fillet(b, b.edges("|Z"), 0.1))

edges("|Z") 表示选中平行于 Z 轴的四条棱，对其倒 0.1 的圆角。

2. 经典 Workplane 风格

import cadquery as cq

# 创建一个带孔的法兰
result = (
    cq.Workplane("XY")
    .box(2, 2, 0.5)
    .faces(">Z")
    .workplane()
    .hole(0.5)
)

# 导出 STEP
cq.exporters.export(result, "flange.step")
# 导出 STL
cq.exporters.export(result, "flange.stl")

逐行说明：

• Workplane("XY").box(2,2,0.5)：在 XY 平面建一个 2×2×0.5 的长方体。
• .faces(">Z").workplane()：选中顶面并在其上新建工作平面。
• .hole(0.5)：打一个直径 0.5 的通孔。
• cq.exporters.export：导出为 CAD 交换格式。

这段代码虽然短，却完整演示了"建体→选面→打孔→导出"的典型流程。实际零件往往是这几步的多次叠加：先建主体，再选不同的面加特征，最后导出。把每一步想清楚再写，比一口气写完再调试要快。导出 STEP 后建议用 FreeCAD 或在线查看器打开核对，确认形状符合预期——脚本里的尺寸和你脑中的设计常常有出入，可视化核对是必要的一步。

建模时的常用思路

CadQuery 的 API 采用"链式调用"风格：先选择一个工作面（Workplane），在其上画二维轮廓（点、线、圆、矩形），再通过拉伸（extrude）、旋转（revolve）、扫掠（sweep）变成三维实体，最后用倒角（fillet）、打孔（hole）、切除（cut）等操作细化。理解"二维轮廓→三维实体→特征修饰"这条主线，就能举一反三构造绝大多数机械零件。

选择面时常用选择器语法：">Z" 表示 Z 值最大的面（顶面），"<Z" 表示底面，"|Z" 表示平行于 Z 轴的边，"#Z" 表示垂直于 Z 轴的面。这些选择器让你能在复杂装配体中精确指定要操作的几何元素，而不必依赖鼠标点选。

3. Jupyter 中可视化

在 Notebook 中直接调用 display：

import cadquery as cq
result = cq.Workplane("XY").sphere(1)
display(result)

4. 参数化零件族

把尺寸写成函数参数，即可批量生成：

def bracket(length, width, thickness):
    return (
        cq.Workplane("XY")
        .box(length, width, thickness)
        .faces(">Z").workplane()
        .hole(width * 0.4)
    )

for w in [10, 15, 20]:
    cq.exporters.export(bracket(50, w, 3), f"bracket_{w}.step")

从图纸到代码的思维转换

新手用 CadQuery 最容易卡住的地方，是还在用"画三视图"的思路想问题。程序化建模的正确姿势是：先想清楚这个零件在三维空间里怎么"长"出来——从一个基本体（长方体、圆柱体、球体）开始，一步步叠加（union）、切除（cut）、倒角。每一步都对应一行代码，而不是在脑海里旋转视图。

建议从简单零件练起：一个带通孔的方块、一个带圆角的支架、一个法兰盘。先在纸上画出草图，标注关键尺寸，再把这些尺寸变成函数参数。遇到建模失败时，用 CQ-editor 的堆栈检查器看每一步生成了什么实体——你会发现多数错误是因为选错了工作面或面选择器没匹配到预期的几何元素。导出 STEP 后，用 FreeCAD 或在线查看器打开验证形状是否符合预期，再回头调整代码。

它和其他 Python 几何库的区别

Python 生态里做几何建模的不止 CadQuery。trimesh 擅长处理三角形网格的加载、合并、布尔运算，偏数据处理；OpenSCAD 是声明式建模语言，渲染质量高但不可编程；Build123d 是 CadQuery 思路的现代继任者，API 更简洁。CadQuery 的定位是"基于 OpenCASCADE 精确内核的参数化实体建模"——它处理的是 B-rep（边界表示）实体，输出 STEP 这种工业标准格式，适合需要精度的机械零件，而不是游戏里的网格模型。

对自动化团队来说，CadQuery 的独特价值在于"模型即代码"：你可以把生成零件的逻辑写成函数，输入参数（如孔距、壁厚），自动产出可加工的 STEP 文件，再接到 CNC 或 3D 打印流程里。这种参数化设计与实验参数联动的能力，在自动化装备定制、科学仪器零件生成等场景非常实用。

导出 STEP 后可导入其他 CAD 软件继续编辑，流程衔接顺畅。

熟练后，参数化建模效率远超手工拖拽。

这正是参数化建模的魅力所在。

七、常见问题 FAQ

下面整理了初次安装与建模时最常遇到的几个疑问，供快速排查参考。失败大多出在 Python 版本超出支持范围、OCP 依赖装不上，下面给出 conda 优先的解决思路。

Q1：pip 安装时报 OCP 相关错误怎么办？
OCP 对 Python 版本与系统 glibc 有要求。确认你的 Python 在 3.9–3.12 范围内，且 pip 已升级到最新。仍失败时改用 conda 安装，或用官方 Docker/apptainer 镜像。

Q2：没有图形界面能看模型吗？
可以。CadQuery 内置基于 trame/vtk 的可视化，会在浏览器或独立窗口中打开模型视图。服务器无头环境可只导出 STEP/STL 文件。

Q3：支持中文参数或单位吗？
CadQuery 内部使用毫米为单位的数值，不绑定显示单位。脚本中用 Python 数值即可，单位约定由你自己管理。

Q4：能和 FreeCAD、SolidWorks 交互吗？
通过 STEP 格式可与绝大多数 CAD 软件交换模型。CadQuery 不直接读取 .sldprt 等私有格式，但 STEP 是通用交换格式。

Q5：如何参与开发？
Fork 仓库后用 mamba env create -n cq-dev -f environment.yml 建开发环境，跑 pytest（官方输出约 200+ 通过）确认无失败，再按 CONTRIBUTING.md 提交 PR。

写在最后

CadQuery 把 3D CAD 从图形界面搬进了 Python 代码，对习惯写程序的人是一种解放。你不需要记住一堆快捷键，只要用函数描述形状，就能得到可版本管理、可参数化、可批量生成的零件模型。它的学习曲线比想象中平缓——掌握"工作面、二维轮廓、拉伸切除"三件套后，大多数机械零件都能拼出来。即使你不做工程，用它把一个想法变成可 3D 打印的实体，也是一次把代码变成实物的有趣体验。

建议动手从一个最简单的零件开始，比如一块带孔的方板，跑通"建体→选面→打孔→导出 STEP"全流程。这个闭环走通后，再去挑战带倒角、放样、阵列的复杂形状，会顺畅很多。遇到报错不要慌，多数是面选择器没选对，用 CQ-editor 看看每一步生成了什么实体就能定位。

以上就是 CadQuery 的本地安装与建模入门。用 Python 脚本描述三维形状，让工程建模变得可版本管理、可自动化。

八、相关链接

• 仓库主页：github.com/CadQuery/cadquery
• 官方文档：cadquery.readthedocs.io
• 速查表：CadQuery Cheatsheet
• CQ-editor：CadQuery/CQ-editor
• 安装指南：Installation

本文命令与版本要求对照仓库 README 整理，Python 支持范围与 API 细节请以官方文档为准。