简介node-occ是一套面向Node.js开发者的OpenCascade扩展致力于在JavaScript环境中完成BREP实体建模与构造实体几何操作适用于CAD工具、Three.js可视化及其他3D建模场景。它通过V8包装器将OpenCascade能力接入Node.js提供类似makeBox、makeCylinder、cut等简洁API支持实体构建、布尔运算与STEP/IGES格式读写并附有可直接运行的示例Web应用。压缩包共105个文件约6.53MB主要包含36个JS示例封装文件、22个C头文件与21个C源文件构成扩展核心另含JSON配置、构建脚本、STEP样件等辅助内容方便二次开发与编译调试。目前已有1914人学习下载。对希望用JavaScript探索参数化建模、或为Three.js场景生成几何数据的开发者这份资源提供了可直接调用的底层能力与可参考的工程实现能帮助快速上手并减少对接OpenCascade的探索成本。 在几何建模这个圈子里OpenCascadeOCCT一直是工业级CAD/CAE的标配内核B-Rep边界表示实体建模能力相当能打。但长期以来想用OCCT基本绕不开C这让一堆做Web应用、搞全栈的兄弟只能眼巴巴看着。node-occ这个项目把OCCT绑到了NodeJS上直接用JavaScript创建、操作、导出BREP实体模型这意味着你可以用一套JS代码打通“浏览器交互 - 服务端几何计算 - 导出STEP/STL给下游加工”的完整链路。这篇文章我从零开始拆解涵盖环境配置、核心API用法、布尔运算实战以及一个法兰盘建模的完整案例适合正在做在线3D建模工具、参数化设计平台或者想在NodeJS后端集成CAD内核的同学参考。1. 项目概述与核心概念1.1 node-occ到底做了什么node-occ本质上是OpenCascade的NodeJS原生插件。它通过V8的C绑定层把OCCT这个庞然大物数万个头文件级别的几何内核暴露成一组JavaScript可调用的API。你不需要在NodeJS里重新实现任何几何算法只需要像调用普通npm包那样调用createBox、booleanCut这类方法底层的C代码就会在堆上构造出OCCT的拓扑结构TopoDS_Shape然后把句柄传回JS侧。这意味着什么一个典型的场景是前台浏览器用Three.js或者React Three Fiber展示模型用户拖拽了几个参数比如长度、孔径、螺距点击“生成”NodeJS后端跑一段node-occ脚本几百毫秒内返回一个STEP文件或者STL文件。以前这种需求要么拆成两个技术栈前端JS后端C服务要么靠一个封装得不太友好的子进程调用OCCT命令行工具维护成本极高。node-occ让整个几何引擎直接内嵌到NodeJS进程里数据不落地内存零拷贝传递开发和部署体验都好了不止一个档次。1.2 BREP与网格建模的差异好多从Three.js入门的同学一听到“实体建模”就以为是在操作Mesh这里必须掰开讲清楚。Mesh网格表示法是用三角形面片去近似一个曲面或实体精度越高面片越多文件越大而BREPBoundary Representation边界表示法记录的是一个实体的拓扑和几何信息顶点Vertex、边Edge、环Wire、面Face、壳Shell、实体Solid以及它们之间的邻接关系。简单说Mesh记录的是“样子”BREP记录的是“模型本身”。用BREP的实体你可以精确查询体积、重心、惯性矩可以随时提取某个面的参数方程可以对两个实体做严格的布尔求交、求差可以得到理论上的精确圆角而不是一堆碎面。这也是工业CAM软件和有限元前处理必须用BREP内核的原因。node-occ把这一整套能力搬到了JavaScript生态让Web开发者不用再去手动处理网格拓扑很多以前觉得“想都不敢想”的几何逻辑现在可以直接用代码表达了。1.3 这个项目适合谁来用说白了node-occ不是那种泛娱乐化的3D库它是给“正经要做参数化设计工具”的人准备的。如果你是做以下事情它非常对路在线配置器比如按用户输入定制钣金件、铝型材开孔、云端的批量几何预处理给CAM/CAE提供输入模型、城市级别的BIM构件参数化生成、甚至在教育场景里让学生写JS来学习实体几何和拓扑概念。它不适合纯做可视化展示的项目那些场景Three.js反而是更轻的选择。2. 环境搭建与依赖安装2.1 NodeJS环境准备安装node-occ的第一步是有一台能跑原生模块的NodeJS环境。Windows上最简单的做法就是去NodeJS官网下载LTS版本安装包一路默认下一步。安装完成后打开PowerShell或者CMD输入node -v和npm -v能输出版本号就说明装好了。这里有个很常见的坑Windows的PowerShell默认执行策略是Restricted运行npm脚本时会提示“npm.ps1因为在此系统上禁止运行脚本”。你不需要去动系统级策略只需要以管理员身份打开PowerShell执行一条命令Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后再重新打开终端npm命令就能正常跑了。另外如果之前装过旧版NodeJS建议先彻底卸载把环境变量里残留的NodeJS路径清干净再装新版避免后面编译原生模块时出现路径混乱的问题。Linux和macOS用户更省事直接通过apt、yum或者homebrew装NodeJS LTS即可。2.2 编译环境与node-occ安装node-occ因为是C插件安装时需要本地编译。Windows用户必须先装好Visual Studio Build Tools安装时勾选“使用C的桌面开发”工作负载以及Windows 10/11 SDK。Linux用户需要g、make、python3多数发行版自带或一条命令就能装齐。macOS用户则需要Command Line Tools运行xcode-select --install即可。准备好编译环境后在项目目录里执行安装npm install node-occ这个过程会下载OpenCASCADE的源码并本地编译耗时比较长五六分钟到半小时都正常取决于机器性能。如果中途失败大概率是编译工具链缺组件按报错提示补齐即可。装完以后写一个最简验证脚本const OCC require(node-occ).init(); // 创建一个10x20x30的盒子 const box OCC.createBox(10, 20, 30); console.log(box created:, !!box); // 导出为STEP文件 OCC.exportStep(box, box.step);如果运行后生成了box.step文件并且没有报错说明环境已经通了。这里需要提醒一下node-occ有不少fork版本个别API方法名存在差异比如有的版本是makeBox有的是createBox。以你实际安装的包为准看下README里的方法列表就行。2.3 常见安装报错排查报错“node-gyp rebuild failed”多半是缺编译工具或NodeJS版本不兼容先确认Visual Studio Build Tools装好了再检查NodeJS版本是否在包的support范围内。报错“cannot find -lTKernel”之类的链接错误OpenCASCADE库文件路径没找对可以试试设置环境变量OCC_INCLUDE_DIR、OCC_LIB_DIR指向OCCT的include和lib目录。报错总在编译最后阶段内存不足导致编译器被杀可以关掉其他大程序或者临时增加系统的swap/虚拟内存。3. 核心细节解析与实操要点3.1 基础几何体创建的底层逻辑node-occ提供了非常经典的基础体构造API本质上是对OCCT的BRepPrimAPI模块做了一层薄封装。创建盒子、圆柱、球体这些操作内部都会先生成对应的参数化曲面比如圆柱面、平面、球面再通过构造器生成拓扑边界。这里“参数化”非常关键——一个圆柱体在BREP里保存的是半径、高度、轴向这些参数而不是几千个三角形顶点。看一段同时创建多个基础体的代码const OCC require(node-occ).init(); // 盒子长宽高 const box OCC.createBox(30, 20, 10); // 圆柱半径5高度40 const cylinder OCC.createCylinder(5, 40); // 球体半径12 const sphere OCC.createSphere(12); // 圆环大半径20小半径6 const torus OCC.createTorus(20, 6); OCC.exportStep(box, box.step); OCC.exportStep(cylinder, cylinder.step); OCC.exportStep(sphere, sphere.step); OCC.exportStep(torus, torus.step);每一条创建语句执行完其实都在内存里构建了一个完整的TopoDS_Solid。这种参数化实体有几个隐藏优点第一文件里可无损保存所有参数第二后续做倒角、抽壳、平移旋转时内核能利用几何连续性执行更精确的运算第三单位非常明确OCCT的默认单位是毫米协调好单位能让下游CAM软件少出幺蛾子。3.2 布尔运算实体编辑的核心建模不是只靠搭积木更多时候是要对实体进行布尔运算也就是并集、差集、交集。node-occ里对应的操作是booleanUnion、booleanCut、booleanIntersection。这三个操作内部都是调用OCCT的BRepAlgoAPI模块处理过程包括计算交点、重新构建拓扑、剔除退化边非常考验内核的鲁棒性。给一个典型例子做一个带中心孔的垫片就是“圆柱体减去小圆柱”const OCC require(node-occ).init(); // 外圆柱半径25厚度8 const outer OCC.createCylinder(25, 8); // 中心通孔半径12 const hole OCC.createCylinder(12, 8); // 求差集得到环形垫片 const gasket OCC.booleanCut(outer, hole); OCC.exportStep(gasket, gasket.step); OCC.exportStl(gasket, gasket.stl);布尔运算的成败非常依赖两个实体的相对位置和尺寸。如果两个面完全共面或者存在极小的间隙内核可能会算出一个拓扑正确的但外观奇怪的形状或者直接报错。实操中我的经验是尽量给参与布尔运算的实体留出微小重叠量避免刚好接触布尔运算后最好用checkShape之类的验证方法检查实体合法性再导出避免把坏模型交给下游。3.3 变换与阵列复制在做法兰盘、齿轮这类重复特征时变换操作配合循环能省很多功夫。平移、旋转、镜像这些操作在node-occ里底层对应OCCT的BRepBuilderAPI_Transform。要注意的是变换不会改变实体本身而是生成一个新的经过变换的实体所以必须用返回值接收变换结果。const OCC require(node-occ).init(); // 先创建一个螺栓孔圆柱体半径5高度15 const boltHole OCC.createCylinder(5, 15); // 沿X轴平移40mm const moved OCC.translate(boltHole, 40, 0, 0); // 绕Z轴旋转45度 const rotated OCC.rotate(moved, 45, Z);实际项目里阵列螺栓孔是特别高频的操作。你可以在一个循环里计算每个孔的位置和角度然后用translaterotate摆到正确的位置最后统一做布尔差集。这里有个性能策略先把单个孔的变换实体收集到一个数组里一次性对底座做多次cut比每次cut都重新遍历整个实体拓扑要快得多。4. 实操过程法兰盘建模完整案例4.1 需求分析与建模思路下面用一个管道法兰盘作为完整案例。学术点讲法兰盘是一个轴对称零件包含一个圆盘主体、一个中心通孔、多个圆周均布的螺栓孔。用手建模都嫌麻烦用代码只要二三十行就能参数化生成改一个螺栓数量就可以得到不同规格的法兰这就是参数化设计的好处。设计参数明确如下法兰外径100mm半径50法兰厚度10mm中心孔直径20mm半径10螺栓孔直径8mm半径4螺栓孔数量6个螺栓孔分布圆直径70mm半径354.2 编写建模脚本先搭主流程创建主体圆柱、开中心孔、生成6个螺栓孔、布尔差集、导出文件。完整代码如下const OCC require(node-occ).init(); // 参数定义 const flangeRadius 50; // 法兰外半径 const flangeHeight 10; // 法兰厚度 const centerHoleRadius 10; // 中心孔半径 const boltHoleRadius 4; // 螺栓孔半径 const boltCircleRadius 35; // 螺栓孔分布圆半径 const boltCount 6; // 螺栓孔数量 // 1. 创建法兰主体 let flange OCC.createCylinder(flangeRadius, flangeHeight); // 2. 挖中心孔 const centerHole OCC.createCylinder(centerHoleRadius, flangeHeight); flange OCC.booleanCut(flange, centerHole); // 3. 生成螺栓孔阵列 const boltHole OCC.createCylinder(boltHoleRadius, flangeHeight); for (let i 0; i boltCount; i) { const angleDeg (360 / boltCount) * i; const angleRad (angleDeg * Math.PI) / 180; const x boltCircleRadius * Math.cos(angleRad); const y boltCircleRadius * Math.sin(angleRad); const posHole OCC.translate(boltHole, x, y, 0); flange OCC.booleanCut(flange, posHole); } // 4. 验证并导出 OCC.checkShape(flange); OCC.exportStep(flange, flange.step); OCC.exportStl(flange, flange.stl, 0.1); console.log(法兰盘建模完成螺栓孔数量, boltCount);流程本身不复杂但有几个细节需要注意。第一boltHole这个圆柱体在循环里被反复复用它本身并没有被修改每次translate生成的是新实体所以循环安全。第二布尔运算的结果依次累加素材少、镜像少的这种情况适合顺序cut性能完全可以接受。第三exportStl的第三个参数是弦高误差值越小、STL越精细、文件也越大对加工件而言0.1mm一般足够如果做流体仿真网格可以设到0.05。4.3 结果验证与下游对接脚本跑完后生成的flange.step可以丢进任何主流CAD软件SolidWorks、Fusion 360、FreeCAD都可以打开检查。我建议接着做个简单测量在FreeCAD里用Part工作台测量一下外径和中心孔直径和设定参数比对正常误差应在0.001mm以内。这种精确性正是BREP的优势Mesh导进来之后一旦经过修模补面误差是微米级别起步的。需要对接CNC加工的话直接在OpenCascade或者CAD软件里把STEP转成刀路之前的毛坯模型再交给CAM软件处理如果只是3D打印验证外形那用node-occ导出的STL也够用了。从一个JS函数到能上机床的模型这个流程闭环了。5. 常见问题与排查技巧实录5.1 API方法名差异问题node-occ的多个发行版本在方法命名上并不统一。有叫booleanCut的也有叫cut的还有叫makeCut的。这挺容易让人卡住。解决办法很简单装上之后打开node_modules/node-occ/README.md或者直接在NodeJS里console.log(Object.keys(OCC))把所有可用的方法名打出来用哪查哪。5.2 精度和布尔运算失败布尔运算失败通常表现为抛异常或者结果shape的边界不对。最常见的诱因是两个参与运算的实体共面/相切或者存在特别小的尺寸差。比如一个半径10.0001的圆柱去减半径10的圆柱看似只是0.0001的差异在OCCT的容差范围内可能被判定为“无法决定内外关系”直接导致拓扑错误。对策是把参与减运算的圆柱稍微做大一点点比如大于目标孔0.01mm让它和母体充分相交得到干净利落的裁剪结果。5.3 性能与内存排查如果是在服务端批量处理几十上百个模型node-occ原生插件的性能通常不是瓶颈但每创建一个实体都在C侧分配内存这些对象在JS侧被回收时是否及时释放不同版本表现不一样。稳妥的做法是每个建模任务跑在独立的worker_threads里处理完成即退出防止内存碎片持续累积。再加上一层结果缓存用参数的哈希作为key同一个模型不会重复计算。5.4 Windows环境下装不上原生编译依赖Windows用户最容易踩的坑是VS Build Tools装错了版本或者压根没装上。一个快速测试方法是运行npm config get msvs_version如果是2019或者2022基本没问题。还会碰到Python版本导致node-gyp失败的Python 3.12之后某些node-gyp版本容易出问题可以临时指定npm config set python python3.11这种办法绕开。6. 扩展思路与我的个人体会node-occ对我来说最大的价值是它让服务器端真正具备了“工业级几何建模能力”而不是停留在展示层面。以前做在线定制工具前端调参数后端只能返回参数很难直接生成几何模型现在一套NodeJS代码就能支撑起从参数校验、实体建模、布尔运算到导出加工文件的完整逻辑接口可以做成纯粹的计算API让任何语言的前端调用都不受影响。我实际用下来最稳妥的落地组合是前端用Three.js看效果后端用Express或者Fastify挂一个node-occ的工作进程任务队列用BullMQ收到参数后走建模流程把STEP/STL文件生成到一个临时目录再给前端返回一个文件下载链接。整个包部署在Docker里唯一要注意的是Docker镜像需要包含OCCT运行库别用一个过于精简的alpine镜像否则启动时加载动态库会失败。最后再分享一个小技巧给所有模型生成统一加一个参数校验层传入node-occ之前先检查尺寸是否为正数、孔距是否小于法兰半径、布尔操作的对象是否都能闭合等等。几何内核虽然强大但并不是“魔法”输入不合理照样崩。加了这层校验你的建模服务才算真正能扛住外部用户的乱点。本文还有配套的精品资源点击获取
node-occ：用JavaScript在NodeJS中实现工业级BREP实体建模与布尔运算
简介node-occ是一套面向Node.js开发者的OpenCascade扩展致力于在JavaScript环境中完成BREP实体建模与构造实体几何操作适用于CAD工具、Three.js可视化及其他3D建模场景。它通过V8包装器将OpenCascade能力接入Node.js提供类似makeBox、makeCylinder、cut等简洁API支持实体构建、布尔运算与STEP/IGES格式读写并附有可直接运行的示例Web应用。压缩包共105个文件约6.53MB主要包含36个JS示例封装文件、22个C头文件与21个C源文件构成扩展核心另含JSON配置、构建脚本、STEP样件等辅助内容方便二次开发与编译调试。目前已有1914人学习下载。对希望用JavaScript探索参数化建模、或为Three.js场景生成几何数据的开发者这份资源提供了可直接调用的底层能力与可参考的工程实现能帮助快速上手并减少对接OpenCascade的探索成本。 在几何建模这个圈子里OpenCascadeOCCT一直是工业级CAD/CAE的标配内核B-Rep边界表示实体建模能力相当能打。但长期以来想用OCCT基本绕不开C这让一堆做Web应用、搞全栈的兄弟只能眼巴巴看着。node-occ这个项目把OCCT绑到了NodeJS上直接用JavaScript创建、操作、导出BREP实体模型这意味着你可以用一套JS代码打通“浏览器交互 - 服务端几何计算 - 导出STEP/STL给下游加工”的完整链路。这篇文章我从零开始拆解涵盖环境配置、核心API用法、布尔运算实战以及一个法兰盘建模的完整案例适合正在做在线3D建模工具、参数化设计平台或者想在NodeJS后端集成CAD内核的同学参考。1. 项目概述与核心概念1.1 node-occ到底做了什么node-occ本质上是OpenCascade的NodeJS原生插件。它通过V8的C绑定层把OCCT这个庞然大物数万个头文件级别的几何内核暴露成一组JavaScript可调用的API。你不需要在NodeJS里重新实现任何几何算法只需要像调用普通npm包那样调用createBox、booleanCut这类方法底层的C代码就会在堆上构造出OCCT的拓扑结构TopoDS_Shape然后把句柄传回JS侧。这意味着什么一个典型的场景是前台浏览器用Three.js或者React Three Fiber展示模型用户拖拽了几个参数比如长度、孔径、螺距点击“生成”NodeJS后端跑一段node-occ脚本几百毫秒内返回一个STEP文件或者STL文件。以前这种需求要么拆成两个技术栈前端JS后端C服务要么靠一个封装得不太友好的子进程调用OCCT命令行工具维护成本极高。node-occ让整个几何引擎直接内嵌到NodeJS进程里数据不落地内存零拷贝传递开发和部署体验都好了不止一个档次。1.2 BREP与网格建模的差异好多从Three.js入门的同学一听到“实体建模”就以为是在操作Mesh这里必须掰开讲清楚。Mesh网格表示法是用三角形面片去近似一个曲面或实体精度越高面片越多文件越大而BREPBoundary Representation边界表示法记录的是一个实体的拓扑和几何信息顶点Vertex、边Edge、环Wire、面Face、壳Shell、实体Solid以及它们之间的邻接关系。简单说Mesh记录的是“样子”BREP记录的是“模型本身”。用BREP的实体你可以精确查询体积、重心、惯性矩可以随时提取某个面的参数方程可以对两个实体做严格的布尔求交、求差可以得到理论上的精确圆角而不是一堆碎面。这也是工业CAM软件和有限元前处理必须用BREP内核的原因。node-occ把这一整套能力搬到了JavaScript生态让Web开发者不用再去手动处理网格拓扑很多以前觉得“想都不敢想”的几何逻辑现在可以直接用代码表达了。1.3 这个项目适合谁来用说白了node-occ不是那种泛娱乐化的3D库它是给“正经要做参数化设计工具”的人准备的。如果你是做以下事情它非常对路在线配置器比如按用户输入定制钣金件、铝型材开孔、云端的批量几何预处理给CAM/CAE提供输入模型、城市级别的BIM构件参数化生成、甚至在教育场景里让学生写JS来学习实体几何和拓扑概念。它不适合纯做可视化展示的项目那些场景Three.js反而是更轻的选择。2. 环境搭建与依赖安装2.1 NodeJS环境准备安装node-occ的第一步是有一台能跑原生模块的NodeJS环境。Windows上最简单的做法就是去NodeJS官网下载LTS版本安装包一路默认下一步。安装完成后打开PowerShell或者CMD输入node -v和npm -v能输出版本号就说明装好了。这里有个很常见的坑Windows的PowerShell默认执行策略是Restricted运行npm脚本时会提示“npm.ps1因为在此系统上禁止运行脚本”。你不需要去动系统级策略只需要以管理员身份打开PowerShell执行一条命令Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后再重新打开终端npm命令就能正常跑了。另外如果之前装过旧版NodeJS建议先彻底卸载把环境变量里残留的NodeJS路径清干净再装新版避免后面编译原生模块时出现路径混乱的问题。Linux和macOS用户更省事直接通过apt、yum或者homebrew装NodeJS LTS即可。2.2 编译环境与node-occ安装node-occ因为是C插件安装时需要本地编译。Windows用户必须先装好Visual Studio Build Tools安装时勾选“使用C的桌面开发”工作负载以及Windows 10/11 SDK。Linux用户需要g、make、python3多数发行版自带或一条命令就能装齐。macOS用户则需要Command Line Tools运行xcode-select --install即可。准备好编译环境后在项目目录里执行安装npm install node-occ这个过程会下载OpenCASCADE的源码并本地编译耗时比较长五六分钟到半小时都正常取决于机器性能。如果中途失败大概率是编译工具链缺组件按报错提示补齐即可。装完以后写一个最简验证脚本const OCC require(node-occ).init(); // 创建一个10x20x30的盒子 const box OCC.createBox(10, 20, 30); console.log(box created:, !!box); // 导出为STEP文件 OCC.exportStep(box, box.step);如果运行后生成了box.step文件并且没有报错说明环境已经通了。这里需要提醒一下node-occ有不少fork版本个别API方法名存在差异比如有的版本是makeBox有的是createBox。以你实际安装的包为准看下README里的方法列表就行。2.3 常见安装报错排查报错“node-gyp rebuild failed”多半是缺编译工具或NodeJS版本不兼容先确认Visual Studio Build Tools装好了再检查NodeJS版本是否在包的support范围内。报错“cannot find -lTKernel”之类的链接错误OpenCASCADE库文件路径没找对可以试试设置环境变量OCC_INCLUDE_DIR、OCC_LIB_DIR指向OCCT的include和lib目录。报错总在编译最后阶段内存不足导致编译器被杀可以关掉其他大程序或者临时增加系统的swap/虚拟内存。3. 核心细节解析与实操要点3.1 基础几何体创建的底层逻辑node-occ提供了非常经典的基础体构造API本质上是对OCCT的BRepPrimAPI模块做了一层薄封装。创建盒子、圆柱、球体这些操作内部都会先生成对应的参数化曲面比如圆柱面、平面、球面再通过构造器生成拓扑边界。这里“参数化”非常关键——一个圆柱体在BREP里保存的是半径、高度、轴向这些参数而不是几千个三角形顶点。看一段同时创建多个基础体的代码const OCC require(node-occ).init(); // 盒子长宽高 const box OCC.createBox(30, 20, 10); // 圆柱半径5高度40 const cylinder OCC.createCylinder(5, 40); // 球体半径12 const sphere OCC.createSphere(12); // 圆环大半径20小半径6 const torus OCC.createTorus(20, 6); OCC.exportStep(box, box.step); OCC.exportStep(cylinder, cylinder.step); OCC.exportStep(sphere, sphere.step); OCC.exportStep(torus, torus.step);每一条创建语句执行完其实都在内存里构建了一个完整的TopoDS_Solid。这种参数化实体有几个隐藏优点第一文件里可无损保存所有参数第二后续做倒角、抽壳、平移旋转时内核能利用几何连续性执行更精确的运算第三单位非常明确OCCT的默认单位是毫米协调好单位能让下游CAM软件少出幺蛾子。3.2 布尔运算实体编辑的核心建模不是只靠搭积木更多时候是要对实体进行布尔运算也就是并集、差集、交集。node-occ里对应的操作是booleanUnion、booleanCut、booleanIntersection。这三个操作内部都是调用OCCT的BRepAlgoAPI模块处理过程包括计算交点、重新构建拓扑、剔除退化边非常考验内核的鲁棒性。给一个典型例子做一个带中心孔的垫片就是“圆柱体减去小圆柱”const OCC require(node-occ).init(); // 外圆柱半径25厚度8 const outer OCC.createCylinder(25, 8); // 中心通孔半径12 const hole OCC.createCylinder(12, 8); // 求差集得到环形垫片 const gasket OCC.booleanCut(outer, hole); OCC.exportStep(gasket, gasket.step); OCC.exportStl(gasket, gasket.stl);布尔运算的成败非常依赖两个实体的相对位置和尺寸。如果两个面完全共面或者存在极小的间隙内核可能会算出一个拓扑正确的但外观奇怪的形状或者直接报错。实操中我的经验是尽量给参与布尔运算的实体留出微小重叠量避免刚好接触布尔运算后最好用checkShape之类的验证方法检查实体合法性再导出避免把坏模型交给下游。3.3 变换与阵列复制在做法兰盘、齿轮这类重复特征时变换操作配合循环能省很多功夫。平移、旋转、镜像这些操作在node-occ里底层对应OCCT的BRepBuilderAPI_Transform。要注意的是变换不会改变实体本身而是生成一个新的经过变换的实体所以必须用返回值接收变换结果。const OCC require(node-occ).init(); // 先创建一个螺栓孔圆柱体半径5高度15 const boltHole OCC.createCylinder(5, 15); // 沿X轴平移40mm const moved OCC.translate(boltHole, 40, 0, 0); // 绕Z轴旋转45度 const rotated OCC.rotate(moved, 45, Z);实际项目里阵列螺栓孔是特别高频的操作。你可以在一个循环里计算每个孔的位置和角度然后用translaterotate摆到正确的位置最后统一做布尔差集。这里有个性能策略先把单个孔的变换实体收集到一个数组里一次性对底座做多次cut比每次cut都重新遍历整个实体拓扑要快得多。4. 实操过程法兰盘建模完整案例4.1 需求分析与建模思路下面用一个管道法兰盘作为完整案例。学术点讲法兰盘是一个轴对称零件包含一个圆盘主体、一个中心通孔、多个圆周均布的螺栓孔。用手建模都嫌麻烦用代码只要二三十行就能参数化生成改一个螺栓数量就可以得到不同规格的法兰这就是参数化设计的好处。设计参数明确如下法兰外径100mm半径50法兰厚度10mm中心孔直径20mm半径10螺栓孔直径8mm半径4螺栓孔数量6个螺栓孔分布圆直径70mm半径354.2 编写建模脚本先搭主流程创建主体圆柱、开中心孔、生成6个螺栓孔、布尔差集、导出文件。完整代码如下const OCC require(node-occ).init(); // 参数定义 const flangeRadius 50; // 法兰外半径 const flangeHeight 10; // 法兰厚度 const centerHoleRadius 10; // 中心孔半径 const boltHoleRadius 4; // 螺栓孔半径 const boltCircleRadius 35; // 螺栓孔分布圆半径 const boltCount 6; // 螺栓孔数量 // 1. 创建法兰主体 let flange OCC.createCylinder(flangeRadius, flangeHeight); // 2. 挖中心孔 const centerHole OCC.createCylinder(centerHoleRadius, flangeHeight); flange OCC.booleanCut(flange, centerHole); // 3. 生成螺栓孔阵列 const boltHole OCC.createCylinder(boltHoleRadius, flangeHeight); for (let i 0; i boltCount; i) { const angleDeg (360 / boltCount) * i; const angleRad (angleDeg * Math.PI) / 180; const x boltCircleRadius * Math.cos(angleRad); const y boltCircleRadius * Math.sin(angleRad); const posHole OCC.translate(boltHole, x, y, 0); flange OCC.booleanCut(flange, posHole); } // 4. 验证并导出 OCC.checkShape(flange); OCC.exportStep(flange, flange.step); OCC.exportStl(flange, flange.stl, 0.1); console.log(法兰盘建模完成螺栓孔数量, boltCount);流程本身不复杂但有几个细节需要注意。第一boltHole这个圆柱体在循环里被反复复用它本身并没有被修改每次translate生成的是新实体所以循环安全。第二布尔运算的结果依次累加素材少、镜像少的这种情况适合顺序cut性能完全可以接受。第三exportStl的第三个参数是弦高误差值越小、STL越精细、文件也越大对加工件而言0.1mm一般足够如果做流体仿真网格可以设到0.05。4.3 结果验证与下游对接脚本跑完后生成的flange.step可以丢进任何主流CAD软件SolidWorks、Fusion 360、FreeCAD都可以打开检查。我建议接着做个简单测量在FreeCAD里用Part工作台测量一下外径和中心孔直径和设定参数比对正常误差应在0.001mm以内。这种精确性正是BREP的优势Mesh导进来之后一旦经过修模补面误差是微米级别起步的。需要对接CNC加工的话直接在OpenCascade或者CAD软件里把STEP转成刀路之前的毛坯模型再交给CAM软件处理如果只是3D打印验证外形那用node-occ导出的STL也够用了。从一个JS函数到能上机床的模型这个流程闭环了。5. 常见问题与排查技巧实录5.1 API方法名差异问题node-occ的多个发行版本在方法命名上并不统一。有叫booleanCut的也有叫cut的还有叫makeCut的。这挺容易让人卡住。解决办法很简单装上之后打开node_modules/node-occ/README.md或者直接在NodeJS里console.log(Object.keys(OCC))把所有可用的方法名打出来用哪查哪。5.2 精度和布尔运算失败布尔运算失败通常表现为抛异常或者结果shape的边界不对。最常见的诱因是两个参与运算的实体共面/相切或者存在特别小的尺寸差。比如一个半径10.0001的圆柱去减半径10的圆柱看似只是0.0001的差异在OCCT的容差范围内可能被判定为“无法决定内外关系”直接导致拓扑错误。对策是把参与减运算的圆柱稍微做大一点点比如大于目标孔0.01mm让它和母体充分相交得到干净利落的裁剪结果。5.3 性能与内存排查如果是在服务端批量处理几十上百个模型node-occ原生插件的性能通常不是瓶颈但每创建一个实体都在C侧分配内存这些对象在JS侧被回收时是否及时释放不同版本表现不一样。稳妥的做法是每个建模任务跑在独立的worker_threads里处理完成即退出防止内存碎片持续累积。再加上一层结果缓存用参数的哈希作为key同一个模型不会重复计算。5.4 Windows环境下装不上原生编译依赖Windows用户最容易踩的坑是VS Build Tools装错了版本或者压根没装上。一个快速测试方法是运行npm config get msvs_version如果是2019或者2022基本没问题。还会碰到Python版本导致node-gyp失败的Python 3.12之后某些node-gyp版本容易出问题可以临时指定npm config set python python3.11这种办法绕开。6. 扩展思路与我的个人体会node-occ对我来说最大的价值是它让服务器端真正具备了“工业级几何建模能力”而不是停留在展示层面。以前做在线定制工具前端调参数后端只能返回参数很难直接生成几何模型现在一套NodeJS代码就能支撑起从参数校验、实体建模、布尔运算到导出加工文件的完整逻辑接口可以做成纯粹的计算API让任何语言的前端调用都不受影响。我实际用下来最稳妥的落地组合是前端用Three.js看效果后端用Express或者Fastify挂一个node-occ的工作进程任务队列用BullMQ收到参数后走建模流程把STEP/STL文件生成到一个临时目录再给前端返回一个文件下载链接。整个包部署在Docker里唯一要注意的是Docker镜像需要包含OCCT运行库别用一个过于精简的alpine镜像否则启动时加载动态库会失败。最后再分享一个小技巧给所有模型生成统一加一个参数校验层传入node-occ之前先检查尺寸是否为正数、孔距是否小于法兰半径、布尔操作的对象是否都能闭合等等。几何内核虽然强大但并不是“魔法”输入不合理照样崩。加了这层校验你的建模服务才算真正能扛住外部用户的乱点。本文还有配套的精品资源点击获取