尧图网站建设 
简介这是一份面向Node.js开发者与CAD/3D建模爱好者的OpenCascade绑定扩展资源用于在服务端以JavaScript构建BREP实体模型。它通过V8包装器将OpenCascade的几何内核能力暴露为简洁API支持布尔运算、STEP/IGES读写等操作适合需要程序化生成或处理三维几何、开展CSG建模与计算机辅助设计实验的中高级开发者。压缩包共105个文件约6.53MB以36个js脚本、22个C头文件与21个cc实现文件为核心辅以json配置、bat构建脚本、yml流程文件及step/stp模型样例另有makefile、gyp等编译工程文件构成从源码绑定到示例应用的完整结构。目前已有1920人学习下载。借助其中的示例Web应用与makeBox、makeCylinder、cut、writeSTEP等调用范例读者可快速理解几何体构造、布尔裁剪与文件导出的实现路径并参考构建脚本完成本地编译为二次开发或集成到自有三维管线提供可复用的基础。1. node-occ 到底在做什么把 OpenCascade 的 BREP 内核搬进 NodeJS如果你写过前端参数化建模或者用 Three.js 拼过 STL 网格大概都遇到过同一个天花板网格模型只能看不能算。想做一个真正的布尔求交、倒角、抽壳或者把模型导出成 STEP 交给下游 CAD纯网格方案立刻露怯。node-occ 这个方向解决的正是这件事——它把 OpenCascadeOCCT这套工业级 BREP 内核通过绑定暴露给 NodeJS让你在 JavaScript 里直接构造实体、做布尔运算、导出标准 CAD 格式。BREP 是 Boundary Representation 的缩写简单说就是用「面 边 顶点」的拓扑结构描述一个实体而不是用三角面片去逼近。这意味着你拿到的是一个数学上精确的几何体圆就是圆不是 64 段折线。node-occ 的价值在于你不用切到 C 或 Python用熟悉的 npm 生态就能驱动这套内核。适合谁做在线参数化设计工具、CAD 插件、3D 打印前处理、或者需要服务端批量生成 STEP/IGES 的团队。下面我从环境搭建一路讲到布尔运算和导出踩坑。2. 环境搭建NodeJS 装好只是第一步OCCT 绑定才是硬骨头2.1 为什么 node-occ 的安装比普通 npm 包麻烦普通 npm 包要么是纯 JS要么带预编译的 .node 二进制。node-occ 属于后者而且它依赖 OpenCascade 的本地库。OCCT 本身是个庞大的 C 工程编译产物在 Windows 上是若干 .dll在 Linux 上是 .so在 macOS 上是 .dylib。node-occ 的绑定层需要链接这些库所以安装过程本质上是「让 Node 的构建工具链找到 OCCT 的头文件和库文件」。常见做法有两种一是用别人预编译好的二进制包省去编译二是自己从源码编译 OCCT再编译绑定层。前者快但版本受限后者慢但可控。我一般建议先在项目里试预编译路径跑不通再转源码编译别一上来就啃 OCCT 的 CMake。这里有个血泪经验NodeJS 的版本和绑定层的 ABI 必须匹配。你用 Node 18 编译的 .node 文件换到 Node 20 上大概率报NODE_MODULE_VERSION不匹配。所以团队里最好用.nvmrc或engines字段锁死 Node 版本别让每个人各装各的。2.2 从零把 NodeJS 和构建工具链准备好先确认 NodeJS 装好。Windows 用户如果遇到npm : 无法加载文件 ... npm.ps1因为在此系统上禁止运行脚本这是 PowerShell 执行策略的问题不是 Node 本身坏了。解决办法是以管理员身份打开 PowerShell执行# 查看当前执行策略 Get-ExecutionPolicy # 设置为 RemoteSigned允许本地脚本运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser改完之后重开终端npm -v应该能正常输出。这一步在 nodejs安装教程 里经常被跳过但它是 Windows 上最高频的翻车点。接下来装构建工具。Linux 上需要 build-essential、cmake、python3macOS 上需要 Xcode Command Line Tools 和 cmakeWindows 上最省事的是装 Visual Studio Build Tools勾选「使用 C 的桌面开发」工作负载再单独装 CMake。# Ubuntu/Debian 一次性装齐 sudo apt update sudo apt install -y build-essential cmake python3 git # macOS xcode-select --install brew install cmake装完后验证cmake --version python3 --versionCMake 版本建议 3.20 以上Python 建议 3.8 以上。node-gyp 在编译原生模块时会调用它们版本太低会报奇怪的配置错误。2.3 安装 node-occ 并验证 BREP 内核是否真的加载成功假设你已经有一个 Node 项目mkdir occ-demo cd occ-demo npm init -y npm install node-occ如果这个包在你的平台上没有预编译产物npm 会触发 node-gyp 编译。编译失败时先看错误日志里有没有Cannot find OCCT或fatal error: Standard_Real.hxx这说明头文件路径没找到。此时需要设置环境变量指向 OCCT 安装目录# Linux/macOS 示例路径按实际安装位置改 export OCCT_ROOT/usr/local/occt export CPLUS_INCLUDE_PATH$OCCT_ROOT/include/opencascade:$CPLUS_INCLUDE_PATH export LD_LIBRARY_PATH$OCCT_ROOT/lib:$LD_LIBRARY_PATHWindows 上对应的是在系统环境变量里加OCCT_ROOT并把%OCCT_ROOT%\win64\vc14\bin加进PATH。装完后写一个最小验证脚本// check.js const occ require(node-occ); // 尝试创建一个最简单的盒子实体 // 参数依次是长度、宽度、高度 const box occ.makeBox(10, 20, 30); if (box) { console.log(BREP 内核加载成功盒子体积, box.volume()); } else { console.error(实体创建失败检查 OCCT 库是否加载); }跑node check.js如果输出体积 6000说明内核通了。如果报Error: Module did not self-register基本是 ABI 不匹配重装 Node 或重编译绑定层。提示不同 node-occ 分支的 API 命名可能不同makeBox只是常见写法之一。以你实际安装版本的导出为准用console.log(Object.keys(occ))先看一遍有哪些方法。3. 用 BREP 构造实体从盒子到布尔运算的最小闭环3.1 BREP 和网格的本质区别决定了你能做什么网格模型STL、OBJ用三角面片逼近曲面一个圆柱侧面可能是 32 个矩形拼出来的。BREP 则保留解析曲面圆柱面就是一个数学意义上的圆柱面带轴线、半径、参数范围。这个区别带来三个实际后果。第一布尔运算的精度。两个网格做差集结果往往有裂缝或自交因为三角面片的交线是近似的。BREP 的布尔运算在曲面级别求交结果拓扑干净。第二倒角和抽壳。网格模型做均匀壁厚抽壳几乎不可能因为偏移方向在三角面片顶点处不唯一。BREP 有法向信息抽壳是标准操作。第三导出格式。STEP、IGES 这些工业格式只认 BREP网格模型导过去要么被拒绝要么被转成大量小平面。所以选 node-occ 而不是 Three.js 的 CSG 库核心动机就是「要精确几何不要视觉近似」。3.2 创建基本体并做第一次布尔运算下面这段代码创建一个盒子再创建一个圆柱从盒子里挖掉圆柱const occ require(node-occ); // 创建基础盒子长 50宽 50高 20 const box occ.makeBox(50, 50, 20); // 创建圆柱半径 10高 40 // 圆柱默认沿 Z 轴中心在原点需要平移让它穿过盒子 const cylinder occ.makeCylinder(10, 40); // 把圆柱沿 Z 轴下移 10保证它完全贯穿盒子 // 参数是实体、dx、dy、dz const movedCylinder occ.translate(cylinder, 0, 0, -10); // 布尔差集box 减去 cylinder const result occ.cut(box, movedCylinder); // 输出结果体积验证运算是否成功 console.log(原始盒子体积, box.volume()); // 50000 console.log(圆柱体积, cylinder.volume()); // 约 12566 console.log(差集后体积, result.volume()); // 约 37434 // 导出为 STEP 格式 occ.writeSTEP(result, result.step);逻辑说明makeBox和makeCylinder返回的是 BREP 实体句柄不是普通 JS 对象。translate返回的是新实体原实体不变这点和可变对象思维不同容易踩坑。cut的第一个参数是被减实体第二个是减去的实体顺序反了结果完全不同。参数说明makeBox的三个参数是 X、Y、Z 方向的尺寸盒子一个角在原点。makeCylinder的前两个参数是半径和高度圆柱底面中心在原点沿 Z 方向生长。translate的位移是相对当前位置的增量不是绝对坐标。3.3 布尔运算的三种模式和常见失败原因OCCT 的布尔运算底层有 BOPBoolean Operations算法常见模式有并集fuse、差集cut、交集common。node-occ 一般会暴露这三个方法。布尔运算失败是高频问题典型现象是返回空实体或抛异常。原因通常有三类一是两个实体没有实际相交差集结果等于原实体交集结果为空二是实体本身有拓扑错误比如自交面或退化边三是容差设置不合理两个面几乎贴合但没完全重合算法判定为相切而非相交。排查手段先单独检查每个实体的isValid()再做布尔。如果实体来自外部导入的 STEP先跑一遍fixShape或sewShape修复拓扑。容差方面OCCT 默认容差是 1e-7 量级如果你的模型尺寸是毫米级这个值通常够用如果模型尺寸是米级可能需要适当放大。// 布尔运算前的健康检查 if (!box.isValid()) { console.error(盒子实体拓扑无效先修复再运算); } if (!cylinder.isValid()) { console.error(圆柱实体拓扑无效); } // 检查两个实体是否有包围盒重叠快速排除不相交的情况 const boxBB box.boundingBox(); const cylBB cylinder.boundingBox(); console.log(盒子包围盒, boxBB); console.log(圆柱包围盒, cylBB);包围盒重叠不代表一定相交但不重叠一定不相交。这个快速检查能省掉很多无效的布尔调用。4. 导出与格式转换STEP、IGES、STL 各自适合什么场景4.1 三种格式的定位差异STEP 是工业界通用的 BREP 交换格式保留完整拓扑和解析曲面适合 CAD 之间传递。IGES 更老对曲面支持好但对实体支持弱现在用得少了。STL 只存三角网格丢失所有解析信息适合 3D 打印和快速预览。node-occ 一般提供writeSTEP、writeIGES、writeSTL三个导出方法。选哪个取决于下游给 SolidWorks 或 FreeCAD 用选 STEP给切片软件用选 STL给老系统对接可能才需要 IGES。// 导出 STEP保留 BREP 精度 occ.writeSTEP(result, output.step); // 导出 STL需要指定网格化精度 // 第二个参数是线性偏差第三个是角度偏差 occ.writeSTL(result, output.stl, 0.1, 0.5); // 导出 IGES occ.writeIGES(result, output.iges);STL 的两个精度参数很关键。线性偏差控制弦高误差值越小网格越密角度偏差控制相邻三角面片的法向夹角值越小曲面越平滑。0.1mm 线性偏差对大多数 3D 打印够用如果模型很大比如 500mm 以上可以放宽到 0.5mm否则文件会大到切片软件卡死。4.2 导出 STEP 时的单位与坐标系陷阱STEP 文件本身带单位声明但不同 CAD 系统对单位的处理不一致。OCCT 内部默认单位是毫米如果你建模时用的是厘米或英寸导出前必须缩放。// 假设模型是按厘米建的导出前转成毫米 const scaled occ.scale(result, 10, 10, 10); occ.writeSTEP(scaled, output_mm.step);坐标系方面STEP 支持装配体层级但 node-occ 导出的通常是单个实体或简单复合体。如果你的模型有多个零件需要保持相对位置导出前要把它们 fuse 成一个复合体或者用writeSTEP的多实体重载如果版本支持。注意导出后务必用另一个 CAD 软件打开验证别只看文件大小。STEP 文件头正常但实体丢失的情况很常见尤其是布尔运算结果有微小裂缝时导出会静默失败。4.3 批量导出的性能与内存控制服务端批量生成 STEP 时内存是主要瓶颈。OCCT 的实体对象在 JS 侧只是句柄真正的几何数据在 C 堆上。如果不主动释放跑几百个模型后进程会 OOM。常见做法是每处理完一个模型就调用释放方法// 处理完一个实体后释放 C 侧资源 result.delete(); box.delete(); cylinder.delete(); movedCylinder.delete();不是所有绑定都提供delete有的用dispose有的靠 GC 自动回收但时机不确定。如果你的版本没有显式释放方法就把批量任务拆成多个子进程每个子进程处理固定数量后退出用进程隔离换内存安全。5. 避坑与排查node-occ 落地时最容易翻车的五个地方5.1 现象npm install 卡在 node-gyp 编译几十分钟不动原因node-gyp 在从源码编译 OCCT 绑定或者下载 OCCT 预编译包时网络超时。Windows 上还可能是 Python 版本不对node-gyp 对 Python 3.12 的支持在某些版本上有问题。解决先确认 Python 版本在 3.8 到 3.11 之间。如果卡在下载设置 npm 镜像或手动下载 OCCT 预编译包放到缓存目录。实在编译不过换用带预编译二进制的 node-occ 分支或者用 Docker 镜像固定环境。5.2 现象布尔运算返回空实体但两个实体明明相交原因实体容差过大或过小导致算法判定面不相交。或者其中一个实体有自交面BOP 算法直接放弃。解决先对每个实体跑isValid()和fixShape()。如果实体来自 STEP 导入导入时设置合适的容差参数。两个实体如果只是面贴合比如盒子底面和另一个盒子顶面共面差集结果可能为空这是数学上正确的需要改成有实际体积重叠。5.3 现象导出的 STEP 在 SolidWorks 里打开是空文件原因导出时实体句柄已经失效或者导出路径没有写权限或者实体本身是壳shell而非实体solid。解决导出前确认实体isSolid()返回 true。如果是壳先sewShape再makeSolid。导出路径用绝对路径避免相对路径在服务端解析到意外目录。导出后立刻用fs.statSync检查文件大小0 字节说明写入失败。5.4 现象STL 导出后文件几百 MB切片软件打不开原因网格化精度设得太细线性偏差 0.01mm 在大模型上会生成千万级三角面片。解决根据模型尺寸动态设精度。模型最大尺寸 100mm 以内用 0.05mm100 到 500mm 用 0.2mm500mm 以上用 0.5mm 到 1mm。角度偏差一般 0.5 弧度够用曲面特别多时可以降到 0.2。5.5 现象Node 进程跑一段时间后崩溃报内存不足原因BREP 实体没有释放C 堆持续增长。JS 的 GC 管不到 C 侧内存。解决每个实体用完显式释放。批量任务用子进程池每个子进程处理 N 个模型后重启。监控process.memoryUsage().rss超过阈值就触发重启。6. 进阶技巧用参数化模板批量生成 BREP 实体6.1 把建模逻辑抽成可配置函数实际项目里很少只建一个盒子。更常见的需求是给定一组参数生成一个带孔、带倒角的零件。把建模步骤封装成函数参数从 JSON 或数据库来。function buildPlate({ length, width, thickness, holeRadius, holeCount }) { // 基础板 let plate occ.makeBox(length, width, thickness); // 沿长度方向均匀打孔 const spacing length / (holeCount 1); for (let i 1; i holeCount; i) { const x spacing * i; const y width / 2; // 创建圆柱并平移到孔位 let hole occ.makeCylinder(holeRadius, thickness * 2); hole occ.translate(hole, x, y, -thickness / 2); // 从板上挖掉 plate occ.cut(plate, hole); hole.delete(); } return plate; } // 批量生成不同规格 const specs [ { length: 100, width: 50, thickness: 5, holeRadius: 3, holeCount: 4 }, { length: 200, width: 80, thickness: 8, holeRadius: 5, holeCount: 6 }, ]; specs.forEach((spec, idx) { const part buildPlate(spec); occ.writeSTEP(part, plate_${idx}.step); part.delete(); });逻辑说明每次cut都返回新实体原实体需要释放。循环里如果不释放中间实体内存会线性增长。holeCount为 0 时循环不执行直接返回基础板这是边界情况测试时要覆盖。参数说明spacing的计算保证孔均匀分布且不贴边。hole的高度设为thickness * 2是为了确保完全贯穿避免因浮点误差导致差集不干净。6.2 验证生成结果的三个手段第一体积校验。理论体积 板体积 - 孔数量 × 单孔体积。和实际volume()对比误差超过 1% 说明布尔运算有问题。第二包围盒校验。生成件的包围盒应该等于[length, width, thickness]如果某个方向偏大说明有游离的碎片没被裁掉。第三导出后用 FreeCAD 命令行做一次checkGeometry这是最可靠的拓扑验证。FreeCAD 的 Python API 可以批量跑# FreeCAD 命令行验证脚本 import FreeCAD import Part shape Part.Shape() shape.read(/path/to/plate_0.step) print(Valid:, shape.isValid()) print(Volume:, shape.Volume) print(Solids:, len(shape.Solids))如果Solids数量大于 1说明布尔运算产生了多个独立实体通常是孔位计算错误导致圆柱没完全在板内。6.3 我踩过的一个参数化坑早期做参数化模板时我把孔位坐标写成了绝对坐标结果换一个板尺寸孔就跑到板外面去了。后来改成相对坐标——所有孔位基于length和width的比例计算换尺寸时自动适配。这个习惯救了我很多次。另一个坑是浮点累积误差。连续做几十次布尔运算后实体的容差会累积最后导出 STEP 时出现微小裂缝。解决办法是每做 10 次布尔运算就fixShape一次把容差重置到默认值。提示参数化模板的测试用例要覆盖极端值比如holeRadius接近width / 2时孔会不会切穿板边holeCount很大时孔间距会不会小于孔径。这些边界在真实项目里一定会被用户触发。如果你正在做在线 CAD 或服务端建模node-occ 这条路值得投入。它把工业级 BREP 能力带进了 JS 生态代价是环境配置和内存管理需要多花心思。我现在的习惯是每个新项目先跑通「建盒子 → 挖孔 → 导 STEP → FreeCAD 验证」这个最小闭环再往上堆业务逻辑。希望帮到你。本文还有配套的精品资源点击获取 node-occ 实战：在 NodeJS 中调用 OpenCascade 进行 BREP 建模与 STEP 导出
简介这是一份面向Node.js开发者与CAD/3D建模爱好者的OpenCascade绑定扩展资源用于在服务端以JavaScript构建BREP实体模型。它通过V8包装器将OpenCascade的几何内核能力暴露为简洁API支持布尔运算、STEP/IGES读写等操作适合需要程序化生成或处理三维几何、开展CSG建模与计算机辅助设计实验的中高级开发者。压缩包共105个文件约6.53MB以36个js脚本、22个C头文件与21个cc实现文件为核心辅以json配置、bat构建脚本、yml流程文件及step/stp模型样例另有makefile、gyp等编译工程文件构成从源码绑定到示例应用的完整结构。目前已有1920人学习下载。借助其中的示例Web应用与makeBox、makeCylinder、cut、writeSTEP等调用范例读者可快速理解几何体构造、布尔裁剪与文件导出的实现路径并参考构建脚本完成本地编译为二次开发或集成到自有三维管线提供可复用的基础。1. node-occ 到底在做什么把 OpenCascade 的 BREP 内核搬进 NodeJS如果你写过前端参数化建模或者用 Three.js 拼过 STL 网格大概都遇到过同一个天花板网格模型只能看不能算。想做一个真正的布尔求交、倒角、抽壳或者把模型导出成 STEP 交给下游 CAD纯网格方案立刻露怯。node-occ 这个方向解决的正是这件事——它把 OpenCascadeOCCT这套工业级 BREP 内核通过绑定暴露给 NodeJS让你在 JavaScript 里直接构造实体、做布尔运算、导出标准 CAD 格式。BREP 是 Boundary Representation 的缩写简单说就是用「面 边 顶点」的拓扑结构描述一个实体而不是用三角面片去逼近。这意味着你拿到的是一个数学上精确的几何体圆就是圆不是 64 段折线。node-occ 的价值在于你不用切到 C 或 Python用熟悉的 npm 生态就能驱动这套内核。适合谁做在线参数化设计工具、CAD 插件、3D 打印前处理、或者需要服务端批量生成 STEP/IGES 的团队。下面我从环境搭建一路讲到布尔运算和导出踩坑。2. 环境搭建NodeJS 装好只是第一步OCCT 绑定才是硬骨头2.1 为什么 node-occ 的安装比普通 npm 包麻烦普通 npm 包要么是纯 JS要么带预编译的 .node 二进制。node-occ 属于后者而且它依赖 OpenCascade 的本地库。OCCT 本身是个庞大的 C 工程编译产物在 Windows 上是若干 .dll在 Linux 上是 .so在 macOS 上是 .dylib。node-occ 的绑定层需要链接这些库所以安装过程本质上是「让 Node 的构建工具链找到 OCCT 的头文件和库文件」。常见做法有两种一是用别人预编译好的二进制包省去编译二是自己从源码编译 OCCT再编译绑定层。前者快但版本受限后者慢但可控。我一般建议先在项目里试预编译路径跑不通再转源码编译别一上来就啃 OCCT 的 CMake。这里有个血泪经验NodeJS 的版本和绑定层的 ABI 必须匹配。你用 Node 18 编译的 .node 文件换到 Node 20 上大概率报NODE_MODULE_VERSION不匹配。所以团队里最好用.nvmrc或engines字段锁死 Node 版本别让每个人各装各的。2.2 从零把 NodeJS 和构建工具链准备好先确认 NodeJS 装好。Windows 用户如果遇到npm : 无法加载文件 ... npm.ps1因为在此系统上禁止运行脚本这是 PowerShell 执行策略的问题不是 Node 本身坏了。解决办法是以管理员身份打开 PowerShell执行# 查看当前执行策略 Get-ExecutionPolicy # 设置为 RemoteSigned允许本地脚本运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser改完之后重开终端npm -v应该能正常输出。这一步在 nodejs安装教程 里经常被跳过但它是 Windows 上最高频的翻车点。接下来装构建工具。Linux 上需要 build-essential、cmake、python3macOS 上需要 Xcode Command Line Tools 和 cmakeWindows 上最省事的是装 Visual Studio Build Tools勾选「使用 C 的桌面开发」工作负载再单独装 CMake。# Ubuntu/Debian 一次性装齐 sudo apt update sudo apt install -y build-essential cmake python3 git # macOS xcode-select --install brew install cmake装完后验证cmake --version python3 --versionCMake 版本建议 3.20 以上Python 建议 3.8 以上。node-gyp 在编译原生模块时会调用它们版本太低会报奇怪的配置错误。2.3 安装 node-occ 并验证 BREP 内核是否真的加载成功假设你已经有一个 Node 项目mkdir occ-demo cd occ-demo npm init -y npm install node-occ如果这个包在你的平台上没有预编译产物npm 会触发 node-gyp 编译。编译失败时先看错误日志里有没有Cannot find OCCT或fatal error: Standard_Real.hxx这说明头文件路径没找到。此时需要设置环境变量指向 OCCT 安装目录# Linux/macOS 示例路径按实际安装位置改 export OCCT_ROOT/usr/local/occt export CPLUS_INCLUDE_PATH$OCCT_ROOT/include/opencascade:$CPLUS_INCLUDE_PATH export LD_LIBRARY_PATH$OCCT_ROOT/lib:$LD_LIBRARY_PATHWindows 上对应的是在系统环境变量里加OCCT_ROOT并把%OCCT_ROOT%\win64\vc14\bin加进PATH。装完后写一个最小验证脚本// check.js const occ require(node-occ); // 尝试创建一个最简单的盒子实体 // 参数依次是长度、宽度、高度 const box occ.makeBox(10, 20, 30); if (box) { console.log(BREP 内核加载成功盒子体积, box.volume()); } else { console.error(实体创建失败检查 OCCT 库是否加载); }跑node check.js如果输出体积 6000说明内核通了。如果报Error: Module did not self-register基本是 ABI 不匹配重装 Node 或重编译绑定层。提示不同 node-occ 分支的 API 命名可能不同makeBox只是常见写法之一。以你实际安装版本的导出为准用console.log(Object.keys(occ))先看一遍有哪些方法。3. 用 BREP 构造实体从盒子到布尔运算的最小闭环3.1 BREP 和网格的本质区别决定了你能做什么网格模型STL、OBJ用三角面片逼近曲面一个圆柱侧面可能是 32 个矩形拼出来的。BREP 则保留解析曲面圆柱面就是一个数学意义上的圆柱面带轴线、半径、参数范围。这个区别带来三个实际后果。第一布尔运算的精度。两个网格做差集结果往往有裂缝或自交因为三角面片的交线是近似的。BREP 的布尔运算在曲面级别求交结果拓扑干净。第二倒角和抽壳。网格模型做均匀壁厚抽壳几乎不可能因为偏移方向在三角面片顶点处不唯一。BREP 有法向信息抽壳是标准操作。第三导出格式。STEP、IGES 这些工业格式只认 BREP网格模型导过去要么被拒绝要么被转成大量小平面。所以选 node-occ 而不是 Three.js 的 CSG 库核心动机就是「要精确几何不要视觉近似」。3.2 创建基本体并做第一次布尔运算下面这段代码创建一个盒子再创建一个圆柱从盒子里挖掉圆柱const occ require(node-occ); // 创建基础盒子长 50宽 50高 20 const box occ.makeBox(50, 50, 20); // 创建圆柱半径 10高 40 // 圆柱默认沿 Z 轴中心在原点需要平移让它穿过盒子 const cylinder occ.makeCylinder(10, 40); // 把圆柱沿 Z 轴下移 10保证它完全贯穿盒子 // 参数是实体、dx、dy、dz const movedCylinder occ.translate(cylinder, 0, 0, -10); // 布尔差集box 减去 cylinder const result occ.cut(box, movedCylinder); // 输出结果体积验证运算是否成功 console.log(原始盒子体积, box.volume()); // 50000 console.log(圆柱体积, cylinder.volume()); // 约 12566 console.log(差集后体积, result.volume()); // 约 37434 // 导出为 STEP 格式 occ.writeSTEP(result, result.step);逻辑说明makeBox和makeCylinder返回的是 BREP 实体句柄不是普通 JS 对象。translate返回的是新实体原实体不变这点和可变对象思维不同容易踩坑。cut的第一个参数是被减实体第二个是减去的实体顺序反了结果完全不同。参数说明makeBox的三个参数是 X、Y、Z 方向的尺寸盒子一个角在原点。makeCylinder的前两个参数是半径和高度圆柱底面中心在原点沿 Z 方向生长。translate的位移是相对当前位置的增量不是绝对坐标。3.3 布尔运算的三种模式和常见失败原因OCCT 的布尔运算底层有 BOPBoolean Operations算法常见模式有并集fuse、差集cut、交集common。node-occ 一般会暴露这三个方法。布尔运算失败是高频问题典型现象是返回空实体或抛异常。原因通常有三类一是两个实体没有实际相交差集结果等于原实体交集结果为空二是实体本身有拓扑错误比如自交面或退化边三是容差设置不合理两个面几乎贴合但没完全重合算法判定为相切而非相交。排查手段先单独检查每个实体的isValid()再做布尔。如果实体来自外部导入的 STEP先跑一遍fixShape或sewShape修复拓扑。容差方面OCCT 默认容差是 1e-7 量级如果你的模型尺寸是毫米级这个值通常够用如果模型尺寸是米级可能需要适当放大。// 布尔运算前的健康检查 if (!box.isValid()) { console.error(盒子实体拓扑无效先修复再运算); } if (!cylinder.isValid()) { console.error(圆柱实体拓扑无效); } // 检查两个实体是否有包围盒重叠快速排除不相交的情况 const boxBB box.boundingBox(); const cylBB cylinder.boundingBox(); console.log(盒子包围盒, boxBB); console.log(圆柱包围盒, cylBB);包围盒重叠不代表一定相交但不重叠一定不相交。这个快速检查能省掉很多无效的布尔调用。4. 导出与格式转换STEP、IGES、STL 各自适合什么场景4.1 三种格式的定位差异STEP 是工业界通用的 BREP 交换格式保留完整拓扑和解析曲面适合 CAD 之间传递。IGES 更老对曲面支持好但对实体支持弱现在用得少了。STL 只存三角网格丢失所有解析信息适合 3D 打印和快速预览。node-occ 一般提供writeSTEP、writeIGES、writeSTL三个导出方法。选哪个取决于下游给 SolidWorks 或 FreeCAD 用选 STEP给切片软件用选 STL给老系统对接可能才需要 IGES。// 导出 STEP保留 BREP 精度 occ.writeSTEP(result, output.step); // 导出 STL需要指定网格化精度 // 第二个参数是线性偏差第三个是角度偏差 occ.writeSTL(result, output.stl, 0.1, 0.5); // 导出 IGES occ.writeIGES(result, output.iges);STL 的两个精度参数很关键。线性偏差控制弦高误差值越小网格越密角度偏差控制相邻三角面片的法向夹角值越小曲面越平滑。0.1mm 线性偏差对大多数 3D 打印够用如果模型很大比如 500mm 以上可以放宽到 0.5mm否则文件会大到切片软件卡死。4.2 导出 STEP 时的单位与坐标系陷阱STEP 文件本身带单位声明但不同 CAD 系统对单位的处理不一致。OCCT 内部默认单位是毫米如果你建模时用的是厘米或英寸导出前必须缩放。// 假设模型是按厘米建的导出前转成毫米 const scaled occ.scale(result, 10, 10, 10); occ.writeSTEP(scaled, output_mm.step);坐标系方面STEP 支持装配体层级但 node-occ 导出的通常是单个实体或简单复合体。如果你的模型有多个零件需要保持相对位置导出前要把它们 fuse 成一个复合体或者用writeSTEP的多实体重载如果版本支持。注意导出后务必用另一个 CAD 软件打开验证别只看文件大小。STEP 文件头正常但实体丢失的情况很常见尤其是布尔运算结果有微小裂缝时导出会静默失败。4.3 批量导出的性能与内存控制服务端批量生成 STEP 时内存是主要瓶颈。OCCT 的实体对象在 JS 侧只是句柄真正的几何数据在 C 堆上。如果不主动释放跑几百个模型后进程会 OOM。常见做法是每处理完一个模型就调用释放方法// 处理完一个实体后释放 C 侧资源 result.delete(); box.delete(); cylinder.delete(); movedCylinder.delete();不是所有绑定都提供delete有的用dispose有的靠 GC 自动回收但时机不确定。如果你的版本没有显式释放方法就把批量任务拆成多个子进程每个子进程处理固定数量后退出用进程隔离换内存安全。5. 避坑与排查node-occ 落地时最容易翻车的五个地方5.1 现象npm install 卡在 node-gyp 编译几十分钟不动原因node-gyp 在从源码编译 OCCT 绑定或者下载 OCCT 预编译包时网络超时。Windows 上还可能是 Python 版本不对node-gyp 对 Python 3.12 的支持在某些版本上有问题。解决先确认 Python 版本在 3.8 到 3.11 之间。如果卡在下载设置 npm 镜像或手动下载 OCCT 预编译包放到缓存目录。实在编译不过换用带预编译二进制的 node-occ 分支或者用 Docker 镜像固定环境。5.2 现象布尔运算返回空实体但两个实体明明相交原因实体容差过大或过小导致算法判定面不相交。或者其中一个实体有自交面BOP 算法直接放弃。解决先对每个实体跑isValid()和fixShape()。如果实体来自 STEP 导入导入时设置合适的容差参数。两个实体如果只是面贴合比如盒子底面和另一个盒子顶面共面差集结果可能为空这是数学上正确的需要改成有实际体积重叠。5.3 现象导出的 STEP 在 SolidWorks 里打开是空文件原因导出时实体句柄已经失效或者导出路径没有写权限或者实体本身是壳shell而非实体solid。解决导出前确认实体isSolid()返回 true。如果是壳先sewShape再makeSolid。导出路径用绝对路径避免相对路径在服务端解析到意外目录。导出后立刻用fs.statSync检查文件大小0 字节说明写入失败。5.4 现象STL 导出后文件几百 MB切片软件打不开原因网格化精度设得太细线性偏差 0.01mm 在大模型上会生成千万级三角面片。解决根据模型尺寸动态设精度。模型最大尺寸 100mm 以内用 0.05mm100 到 500mm 用 0.2mm500mm 以上用 0.5mm 到 1mm。角度偏差一般 0.5 弧度够用曲面特别多时可以降到 0.2。5.5 现象Node 进程跑一段时间后崩溃报内存不足原因BREP 实体没有释放C 堆持续增长。JS 的 GC 管不到 C 侧内存。解决每个实体用完显式释放。批量任务用子进程池每个子进程处理 N 个模型后重启。监控process.memoryUsage().rss超过阈值就触发重启。6. 进阶技巧用参数化模板批量生成 BREP 实体6.1 把建模逻辑抽成可配置函数实际项目里很少只建一个盒子。更常见的需求是给定一组参数生成一个带孔、带倒角的零件。把建模步骤封装成函数参数从 JSON 或数据库来。function buildPlate({ length, width, thickness, holeRadius, holeCount }) { // 基础板 let plate occ.makeBox(length, width, thickness); // 沿长度方向均匀打孔 const spacing length / (holeCount 1); for (let i 1; i holeCount; i) { const x spacing * i; const y width / 2; // 创建圆柱并平移到孔位 let hole occ.makeCylinder(holeRadius, thickness * 2); hole occ.translate(hole, x, y, -thickness / 2); // 从板上挖掉 plate occ.cut(plate, hole); hole.delete(); } return plate; } // 批量生成不同规格 const specs [ { length: 100, width: 50, thickness: 5, holeRadius: 3, holeCount: 4 }, { length: 200, width: 80, thickness: 8, holeRadius: 5, holeCount: 6 }, ]; specs.forEach((spec, idx) { const part buildPlate(spec); occ.writeSTEP(part, plate_${idx}.step); part.delete(); });逻辑说明每次cut都返回新实体原实体需要释放。循环里如果不释放中间实体内存会线性增长。holeCount为 0 时循环不执行直接返回基础板这是边界情况测试时要覆盖。参数说明spacing的计算保证孔均匀分布且不贴边。hole的高度设为thickness * 2是为了确保完全贯穿避免因浮点误差导致差集不干净。6.2 验证生成结果的三个手段第一体积校验。理论体积 板体积 - 孔数量 × 单孔体积。和实际volume()对比误差超过 1% 说明布尔运算有问题。第二包围盒校验。生成件的包围盒应该等于[length, width, thickness]如果某个方向偏大说明有游离的碎片没被裁掉。第三导出后用 FreeCAD 命令行做一次checkGeometry这是最可靠的拓扑验证。FreeCAD 的 Python API 可以批量跑# FreeCAD 命令行验证脚本 import FreeCAD import Part shape Part.Shape() shape.read(/path/to/plate_0.step) print(Valid:, shape.isValid()) print(Volume:, shape.Volume) print(Solids:, len(shape.Solids))如果Solids数量大于 1说明布尔运算产生了多个独立实体通常是孔位计算错误导致圆柱没完全在板内。6.3 我踩过的一个参数化坑早期做参数化模板时我把孔位坐标写成了绝对坐标结果换一个板尺寸孔就跑到板外面去了。后来改成相对坐标——所有孔位基于length和width的比例计算换尺寸时自动适配。这个习惯救了我很多次。另一个坑是浮点累积误差。连续做几十次布尔运算后实体的容差会累积最后导出 STEP 时出现微小裂缝。解决办法是每做 10 次布尔运算就fixShape一次把容差重置到默认值。提示参数化模板的测试用例要覆盖极端值比如holeRadius接近width / 2时孔会不会切穿板边holeCount很大时孔间距会不会小于孔径。这些边界在真实项目里一定会被用户触发。如果你正在做在线 CAD 或服务端建模node-occ 这条路值得投入。它把工业级 BREP 能力带进了 JS 生态代价是环境配置和内存管理需要多花心思。我现在的习惯是每个新项目先跑通「建盒子 → 挖孔 → 导 STEP → FreeCAD 验证」这个最小闭环再往上堆业务逻辑。希望帮到你。本文还有配套的精品资源点击获取