在做三维 CAD 相关项目时，最常被问到一个问题：“能不能不开软件，直接在浏览器里搞实体建模？”过去工程师听到这话通常会摇头——实体建模不是简单画个立方体，靠的是 BRep、拓扑、布尔求交这些硬核内核，传统上这些都是桌面软件的天下。但现在，Solid Modeling in your Browser 已经从概念验证走到真正的可落地阶段，WebAssembly 把 OpenCascade 这样的工业级几何内核搬进了浏览器，WebGL/WebGPU 把渲染性能拉到了接近原生水平。这篇文章就围绕“如何在浏览器里实现实体建模”这件事，从原理、选型、实操到踩坑，完整梳理一遍。不管你是有 CAD 背景的工程师，想给现有工具做 Web 化，还是纯粹好奇前端怎么啃下几何内核这块硬骨头，这篇都值得一看。
1. 整体设计思路：为什么要在浏览器里做实体建模
1.1 实体建模的本质：先搞懂“实体”和“建模”分别难在哪
实体建模（Solid Modeling）和表面建模（Surface Modeling）最大的不同在于：实体模型内部有严格的拓扑信息，知道哪条边连着哪个面、哪个面围成哪个体，能做质量属性计算、布尔运算、有限元前处理。浏览器里做实体建模，不是一个“用 Three.js 画个 3D 图形”那么简单的事。Three.js 本身是个渲染引擎，它只在乎顶点、法线、材质，完全不知道你画的是不是一个“实体”。
所以核心难点不在渲染，而在“几何内核”。几何内核负责维护模型的数据结构、执行布尔运算、生成倒角、抽壳等操作。最经典的内核有 Parasolid、ACIS、OpenCascade，前两者是商业闭源，OpenCascade 是开源的。过去 OpenCascade 以 C++ 库形式使用，现在通过 Emscripten 编译成 WebAssembly 后，可以直接在浏览器里运行，保留了大部分建模能力。
在这一步，思路要很清楚：浏览器是“壳”，提供渲染和交互；几何内核才是“魂”，负责真正的实体建模计算。两者通过轻量级数据桥接，一个偏 GPU 渲染，一个偏 CPU 计算，各干各的，才能把网页变成一台“云端工作站”。
1.2 浏览器环境的天然限制，以及为什么现在突破口出现了
浏览器做实体建模，过去有三座大山：计算性能、渲染能力、文件 IO。
计算性能方面，JS 解释执行确实慢，但 WebAssembly 把 C++ 代码编译成接近原生的指令，OpenCascade.js 实测做几百个实体的布尔运算也能达到可用水平。渲染能力方面，WebGL 已经足够处理中等规模的装配体，WebGPU 的出现更是把渲染上限抬高了一个量级。文件 IO 方面，浏览器出于安全拿不到本地文件系统，但 File System Access API、拖拽解析、纯内存数据传递等方式，已经让“打开 STP、保存 STEP”这类操作变得顺畅可行。
这些突破凑到一起，意味着什么？意味着你可以把实体建模能力直接嵌进网页、嵌进低代码平台、嵌进协同设计工具，用户零安装、免授权，打开链接直接上手。对工业软件厂商来说，这是降本增效的路径；对独立开发者来说，这是把 CAD 平民化的机会。
1.3 技术选型对比：Three.js + OpenCascade.js、@react-three/cad、自研内核
真正做技术选型时，市面上能打的方案其实不多。我试过几类：
第一类是 Three.js 加 OpenCascade.js，这也是最主流的组合。OpenCascade.js 是 OpenCascade 的 WASM 封装，维护了 BRep 数据结构，提供近乎完整的拓扑操作；Three.js 负责显示网格。工作流是：用 OCCT 的 API 建模，然后用内置的 Tessellation 把 BRep 三角面片化，再把三角形数据塞给 Three.js 渲染。优点是可定制性强、社区案例多，缺点是学习曲线陡。
第二类是 @react-three/cad，它把 OpenCascade 和 React 生态做结合，用 JSX 描述实体模型。写起来非常舒服，比如<box>、<cylinder>这种标签定义特征，然后自动做布尔运算。适合前端团队快速搭原型，但遇到特别复杂的制造业需求，还是会显得力不从心。
第三类是自己写简化几何内核，比如只用 CSG 布尔运算，配合 Three.js 的 BufferGeometry。这种方法适合做文创、教育、简单产品自定义类的轻量建模，但毕竟不是工业级，拓扑检查、圆角、变半径倒角这些根本做不了。
我个人的建议是：项目目标如果是面向制造、模型要进加工或仿真，直接上 OpenCascade.js；如果只是做三维展示和简单参数化成型，用 CSG 就够。下面整套实操我都围绕 OpenCascade.js 展开，因为它最能体现“实体建模”这四个字的分量。
2. 核心原理与基础实现：几何内核是怎么在浏览器里跑起来的
2.1 从数学到图形：BRep 和 CSG 是如何表达同一个模型的
实体建模有两种基础表达方式：BRep 和 CSG。
BRep，即边界表示法（Boundary Representation），把实体拆成壳、面、环、边、顶点五层拓扑结构，每层有对应的几何信息：面是 NURBS 曲面，边是曲线，顶点是坐标点。这种表达精确、支持复杂的自由曲面，是 OpenCascade 的看家本领。浏览器里做实体建模，如果追求工业精度，就必须拥抱 BRep。
CSG，即构造实体几何法（Constructive Solid Geometry），用基本体如立方体、球、圆柱，通过并、交、差的布尔运算组合出复杂模型。它更像是“建模脚本”，不存最终的面，只存过程树。CSG 思路很适合参数化改型，但在显示前还是得先生成网格。
在浏览器实现中，两者其实是配合使用的。OpenCascade.js 底层就是用 BRep 管理数据，对外提供布尔运算 API，而 CSG 只是用户层面的建模逻辑。简单理解：你说是用盒子挖个槽，代码层是 CSG 思维；真正执行布尔挖槽时，底层是 BRep 曲面求交、拓扑重建。对初学者，先记住：显示出来的三角网格只是“渲染代理”，真正的实体还在内核里以 BRep 数据活着。
2.2 参数化建模的几何内核：一个特征树在浏览器里如何运转
工业建模软件几乎都有特征树，浏览器实现思路也一样。你创建了一个长方体，定义长宽高参数；再创建一个圆柱，参与差集，来挖一个孔；修改参数时，整棵树重新求值。
这个过程在浏览器里分三步：第一步，遍历特征树上的每个操作节点；第二步，调用 OpenCascade.js 的建模 API 依次构建或修改 BRep 实体；第三步，对修改后的实体重新做三角化，并把新网格同步到渲染引擎。
要注意的是，这种“重现求值”机制对内存很敏感。每次修改，OpenCascade.js 会在 WASM 堆里生成新对象，旧对象需要手动释放，否则内存越吃越大。实操中我习惯写一个“几何缓存清理器”：每次特征树更新完，调用oc.delete系列方法释放临时实体，只保留根节点。这听起来麻烦，但跑过几千次参数修改后，你就能感受到差距：清理干净的和不清理的，内存占用能差几十倍。
2.3 几何计算与渲染隔离：为什么不要在 GPU 端做布尔运算
初学者容易踩的一个坑：试图直接在 Three.js 场景里做布尔运算，比如用THREE.BufferGeometry做 CSG。这当然能跑，但千万别把这条路当作“实体建模”。Three.js 的几何体本质是三角形网格，没有拓扑信息；对它做差集，结果在视觉上看着对，但边缘可能是破的、内部面方向是乱的，导出去直接没法用。
正确的架构是：计算在 CPU 端完成，渲染才交给 GPU。整个流程是：WASM 内核计算生成 BRep → 对 BRep 做曲面离散化得到网格 → 网格传到 GPU 缓冲区 → WebGL/WebGPU 着色器渲染。这样既能保证模型精度，又能利用 GPU 的多边形填充能力。
这里体现了一个关键理念：浏览器里的实体建模，其实是一个“跨语言、跨运行时”的协作系统。JavaScript 负责界面和交互，WASM 负责几何计算，WebGL/WebGPU 负责显示。把这三层想清楚，后面看代码就不会晕。
3. 实操：在浏览器里实现一个可交互的实体建模工具
3.1 准备基础环境：Vite、TypeScript 与 OpenCascade.js 的引入
我先说结论，这套组合包你用得顺：Vite + TypeScript +openccascade这个 npm 包 + Three.js。
为什么选 Vite？因为它对 WASM 文件加载支持清晰，直接能处理.wasm资源，不用手动配一堆 loader。为什么选 TypeScript？因为 OpenCascade 的 API 对象超大，有类型提示能省一半查文档时间。
初始化项目：
npm create vite@latest solid-modeling-web -- --template vanilla-ts cd solid-modeling-web npm install three @types/three openccascade注意这个包名是openccascade，两个 c，不是opencascade。它针对 Emscripten 模块做了封装，派生了很多易用的工厂函数。如果你不用这个包，也可以直接加载 OpenCascade 官方编译的 WASM 文件。
Vite 配置里需要做两件事：一是优化依赖，二是处理 WASM 的加载方式。我习惯这样配：
// vite.config.ts import { defineConfig } from 'vite'; export default defineConfig({ optimizeDeps: { exclude: ['openccascade'] }, assetsInclude: ['**/*.wasm'] });optimizeDeps.exclude是为了防止 Vite 预构建 WASM 时出问题，让包在运行时动态加载。这一步能避免很多诡异报错。
接下来初始化 OpenCascade 实例。这个实例是全局单例，里面藏着所有 OCCT 类函数。我建议封装成一个异步模块：
import opencascade from 'openccascade'; let oc: any; export async function getOC() { if (!oc) { oc = await opencascade({ locateFile: (path: string) => { // 返回 wasm 文件路径 if (path.endsWith('.wasm')) return `/${path}`; return path; } }); } return oc; }有个容易忽略的细节：OpenCascade WASM 可能附带一个.data文件，里面存放系统数据。出于性能考虑，建议把这些大文件放到 CDN 或服务器的静态目录，并配置cache-control，让浏览器缓存，第二次加载能快很多。
3.2 创建基础实体与布尔运算：用 50 行代码做一个“圆角法兰盘”
下面按我的实际做法，展示从创建实体到布尔运算的完整流程。先不搞复杂 UI，就在控制台看结果。
第一步，创建两个实体：一个圆柱，一个棱柱孔。
import * as THREE from 'three'; import { getOC } from './oc'; async function createFlange() { const oc = await getOC(); // 创建一个圆柱体：半径 10，高度 5 const cylinder = new oc.BRepPrimAPI_MakeCylinder( new oc.gp_Ax2( new oc.gp_Pnt(0, 0, 0), new oc.gp_Dir(0, 0, 1) ), 10, 5 ).Shape(); // 创建一个立方体：长 6、宽 6、高 5（用于挖孔） const box = new oc.BRepPrimAPI_MakeBox( new oc.gp_Pnt(-3, -3, 0), new oc.gp_Pnt(3, 3, 5) ).Shape(); // 执行差集：圆柱减去立方体 const cutShape = new oc.BRepAlgoAPI_Cut(cylinder, box); cutShape.Build(); if (!cutShape.IsDone()) { throw new Error('布尔运算失败'); } const result = cutShape.Shape(); // 到这里，result 就是一个带方孔的法兰盘实体 }注意几个细节：
BRepPrimAPI_MakeCylinder的最后一个参数是角度，默认给 (2\pi) 就是完整圆柱。如果要扇形，可以传一个角度值，OpenCascade 会自动构建。- 布尔运算类必须先调用
Build()，再检查IsDone()，不能跳过，否则拿到的 shape 是脏数据。 - 如果你要做更多步骤，比如倒角，可以继续用
BRepFilletAPI_MakeFillet，对刚才结果的边做圆角。这个类需要传入边的拓扑对象，需要遍历TopExp_Explorer找边，代码会多一截，但原理和上面一致。
布尔运算用的BRepAlgoAPI_Cut是 OCCT 里最常用的差集。它内部支持并行计算，WASM 单线程下可能没那么快，所以对小模型没感觉，大模型就能感到明显差异。这里我建议数据量大的时候用 Web Worker 隔离几何计算，防止阻塞 UI。
3.3 把 BRep 变成三角形网格：核心的 Tessellation 环节
现在实体有了，但浏览器渲染引擎不认 BRep，必须把曲面切成三角形。OpenCascade 内置了网格化工具，叫BRepMesh_IncrementalMesh。用法如下：
function shapeToBufferGeometry(shape: any, oc: any, deflection: number = 0.1) { const mesh = new oc.BRepMesh_IncrementalMesh(shape, deflection); mesh.SetDeflection(deflection); mesh.Perform(); // 使用 TopExp_Explorer 遍历面 const explorer = new oc.TopExp_Explorer(shape, oc.TopAbs_FACE); const positions: number[] = []; const indices: number[] = []; while (explorer.More()) { const face = oc.TopFace(explorer.Current()); // 把面转成三角剖分 const triangulation = oc.BRep_Tool.Triangulation(face, mesh.GetDeflection()); if (!triangulation.IsNull()) { // 这里有坑，见下文 } explorer.Next(); } // 组装 THREE.BufferGeometry }这里还有个更简单的路径：直接用 OpenCascade.js 内置的oc.Mesh组件，或者借助第三方工具occt-import-js的brepToMesh方法。我自己更喜欢用occt-import-js，因为它把网格解析封装得十分到位，直接返回顶点数组和索引数组，省去自己遍历面的痛苦。
import { initOCCT } from 'occt-import-js'; const occt = await initOCCT(); const meshData = occt.brepToMesh(result); // result 是 BRep 实体 // meshData.vertex_arr, meshData.index_arr拿到数组后，就能创建一个THREE.BufferGeometry：
const geometry = new THREE.BufferGeometry(); geometry.setAttribute('position', new THREE.Float32BufferAttribute(meshData.vertex_arr, 3)); geometry.setIndex(meshData.index_arr); geometry.computeVertexNormals();这里有个容易踩的坑：OpenCascade 的三角化结果不是每个顶点独立，而是多个面共用顶点，所以数组里会有重复顶点。直接塞给 Three.js 没问题，但要做网格简化或后续编辑时，尽量先做一遍顶点去重，不然模型会多出几个数量级的顶点，白占内存。
另外，deflection这个参数非常关键。它决定三角形网格与理想曲面的最大允许偏差。数值越小，网格越密，模型越精细。经验值是：预览用 0.1，导出用 0.01，3D 打印用 0.005。如果直接用默认值，有些圆角在大尺寸下会棱角分明，打印出来粗糙得一塌糊涂。
3.4 交互视图、鼠标拾取和基础变换
实体建模工具不能只有一个静态模型，必须支持旋转、平移、缩放，还要能点击选中某个面或实体。Three.js 的OrbitControls是最省事的相机控制方案：
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'; const renderer = new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); document.body.appendChild(renderer.domElement); const scene = new THREE.Scene(); const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000); camera.position.set(30, 40, 30); camera.lookAt(0, 0, 0); const controls = new OrbitControls(camera, renderer.domElement);选择功能就要复杂一些。你可以用THREE.Raycaster做屏幕射线检测，点击返回网格上的三角形，再通过“三角形所属原 BRep 面”的映射，找到对应的拓扑面 ID。我建议在创建网格时，把网格每个三角形的索引绑定到 BRep 面 ID 上，这样点击后能准确高亮显示某个面，这也是工业软件常见交互。
绑定方式不复杂：遍历 BRep 的面时，对每个面生成单独的网格，存到一个二维数组里。渲染时把它们合并成一个几何体，但三角形索引保留分组标签。点击时先判断命中三角形，再查它是哪个组，就知道选中的是哪个面了。如果需要在面上做草绘、标注，这个映射关系是必须的。
3.5 模型导出：STL、STEP、OBJ 以及那些“本地文件”限制
一个不能导出的建模工具等于没有。在浏览器里导出有几条路：
- STEP 格式：这是制造业通用的 BRep 交换格式，导出后可以进 SolidWorks、Fusion 360 这类软件继续编辑。OpenCascade 提供
STEPControl_Writer，直接调用即可。 - STL 格式：纯三角网格格式，适合 3D 打印，但丢失拓扑。OpenCascade 里可以用
StlAPI_Writer，或者直接导出我们生成的网格数据。 - OBJ 格式：也是网格格式，Web 生态最熟悉。用 Three.js 的
OBJExporter就能搞定。
STEP 导出代码长这样：
const writer = new oc.STEPControl_Writer(); writer.Transfer(result, oc.STEPControl_AsIs); const status = writer.Write('model.step');但在浏览器里没法直接往磁盘写文件。正确的做法是把文件数据放进 Blob，生成临时 URL，触发下载。
function downloadFile(content: string | Blob, filename: string) { const blob = content instanceof Blob ? content : new Blob([content]); const link = document.createElement('a'); link.href = URL.createObjectURL(blob); link.download = filename; link.click(); URL.revokeObjectURL(link.href); }于是导出 STEP 就变成：
// 把 STEP 写进内存字符串 const writer = new oc.STEPControl_Writer(); writer.Transfer(result, oc.STEPControl_AsIs); // 这里需要重定向写文件的内存路径，或者直接用 OCC 的内存输出版本 const data = await oc.FS.readFile('/model.step'); downloadFile(data, 'model.step');说到本地文件，很多人会碰到这么一条提示：your browser does not allow to read local files。这其实是浏览器的安全模型在起作用：网页默认拿不到你硬盘上的文件，除非你主动通过文件选择框授权。如果你要做一个“打开本地 STEP 文件”功能，最优雅的方式是用<input type="file">结合 File System Access API。
const input = document.createElement('input'); input.type = 'file'; input.accept = '.step,.stp,.stl'; input.onchange = async (event) => { const file = (event.target as HTMLInputElement).files?.[0]; if (!file) return; const text = await file.text(); // 把 text 交给 OpenCascade 的 STEPControl_Reader 解析 }; input.click();更进一步，如果浏览器支持showOpenFilePicker()，用户可以重新授权同一个文件，再次保存时能直接写回原文件，体验非常接近桌面软件。不过兼容性还依赖 Chromium 内核，Firefox 和 Safari 暂时不行，所以还是保留文件选择框作为兜底。
4. 常见问题与排查技巧实录
4.1 浏览器本地文件读写限制：为什么不能直接读本地文件，以及怎么破
这是 Web 端实体建模工具最大的体验障碍之一。浏览器不允许网页 JS 任意读本地文件，是为了防止恶意网页偷你的数据。但这也让很多“一键打开模型”的功能变得繁琐。
我试过几种方案：
- 拖拽解析：用户把文件拖到指定区域，浏览器允许在 drop 事件里读取文件，这是最顺滑的方式，适合导入 STL/OBJ 等文本或二进制网格。
<input type="file">：最通用，兼容所有浏览器。- File System Access API：能拿到文件句柄，支持“保存到原文件”的体验，但目前只覆盖 Chromium 系。
核心策略是：把“文件读取”这个动作设计得尽量像本地软件，但要尊重浏览器安全边界。不要让用户去搭建本地服务器、关闭安全策略，那既不安全，也不符合主流体验。
另外，很多后端接口也有限制，比如大文件导入内存受限。一个 200MB 的 STEP 文件在浏览器里可能解析几分钟。建议前端加进度提示，同时把解析过程放到 Web Worker，避免页面卡死。
在网络上搜索时，经常看到 “db browser for sqlite” 或者其他无关键盘记录，注意不要简单照抄，那些并不是建模工具的重点，只是一些浏览器的附加功能。我们的核心是实体建模。
4.2 布尔运算失败或模型异常：容差、非流形和方向问题
布尔运算是最容易出问题的环节。典型的报错包括BRepAlgoAPI_Cut失败、生成的模型出现破面、内部有残留边线。原因大多出在容差和非流形几何上。
OCCT 默认容差是 (10^{-7}) 毫米级别，而浏览器里很多模型的数据来自不同软件，导入后可能存在微小缝隙，导致求交不稳定。解决办法是统一建模环境：
- 所有顶点坐标保留到小数点后三位以上，避免单精度浮点误差。
- 对导入的几何做
ShapeFix_Shape，它专门修复破损形状，特别适合处理外部导入模型。 - 做布尔运算前，务必检查两个实体是否“可流水线化”，也就是没有退化边、重叠面、自相交。可以先用
BRepCheck_Analyzer做一次合法性检查。
| 症状 | 可能原因 | 排查思路 |
|---|---|---|
| 布尔运算直接失败 | 实体没有正确封闭 | 使用 BRepCheck 检查封闭性 |
| 运算成功但圆角溢出 | 倒角半径大于壁厚 | 检查几何尺寸，减小半径 |
| 面数爆炸 | 容差设置太小 | 调大 deflection 或合并曲面 |
| 导出 STEP 后打不开 | 模型存在非流形边 | 做单位转换和 ShapeFix |
这类问题没有一劳永逸的解法，核心经验是：永远要在进入布尔运算前做一次“几何体检”，养成习惯，能省掉一半的 debug 时间。
4.3 性能问题：大型装配体在浏览器里卡成 PPT 怎么办
浏览器建模工具最容易翻车的就是性能。实体建模数据量一大，内存和渲染双双告急。
渲染层面，最简单的优化是用实例化渲染：同一个零件有多个实例时，只存一份几何，通过变换矩阵画很多份。Three.js 提供了InstancedMesh，几千个螺栓都不成问题。
CPU 几何计算层面，必须把 OpenCascade.js 放到 Web Worker。主线程负责交互和渲染，Worker 负责布尔运算和网格化。用postMessage传递 ArrayBuffer，几何数据可以避免结构化克隆的高昂开销。
我实际做过一个 500 个零件的装配体，用 Worker 并行计算，每个零件的网格化耗时从主线程的 80ms 降到 Worker 的 70ms，虽然单线程没有太大提升，但好处是界面不卡了。如果再用多个 Worker 做流水线处理，整体吞吐量能翻几倍。
还有一个被忽略的点：内存泄漏。OpenCascade.js 的 WASM 堆需要手动管理，每次创建临时对象用完都要delete。可以封装一个withOC(shape, fn)的辅助函数，自动释放临时实体，异常时也走 finally 清理。这套机制跑起来很稳，能有效防止页面长时间使用后崩掉。
4.4 顺带聊一下：Browser Use MCP 和 Playwright MCP 有什么区别
既然是在浏览器里做建模工具，免不了要自动化测试交互流程。很多人会问 “browser use mcp 与 playwright mcp 有什么区别”。这不是建模本身的问题，但和建模工具的开发体验相关。
简单说，Playwright MCP 是一个基于 Playwright 的模型上下文协议（Model Context Protocol）服务，它让 AI 助手能直接控制浏览器页面，执行点击、输入、截图等操作。而 Browser Use MCP 更像是一个通用的浏览器自动化支持层，重点在“让模型学会如何使用浏览器”。
在建模工具的测试里，我通常用 Playwright MCP 来跑 E2E 用例：打开页面、加载模型、旋转相机、点击几个按钮、导出 STL。它能快速生成可复现的测试脚本。但要注意，WebAssembly 在 Playwright 环境下加载有时会慢，这会导致测试超时，建议等待一个特殊的全局标志（比如window.ocReady）再继续操作。
这类 MCP 工具本身是给 AI 编程用的，不是建模工具的核心环节。但如果你想把“浏览器里的 CAD”和 AI 结合，做成“你用自然语言告诉 AI 建个带孔的板子，AI 自动操作建模界面完成参数修改”，那 MCP 确实是最快落地的技术路线。
5. 工程化经验、踩坑记录与扩展方向
5.1 工程化封装：项目结构的进化和优化思路
刚开始做的时候，我图省事，把 OpenCascade 的调用直接写在组件里。到了后期，代码越来越乱，每加一个功能都像在一堆意大利面里捞面条。后来我重构了一遍，分层很有效：
- 渲染层：只负责 Three.js 场景、相机、渲染器、控制器。
- 几何服务层：封装 OpenCascade 的创建、布尔、倒角、网格化，对外提供异步 API。
- 特征管理层：维护特征树和参数，跟几何层解耦。
- 状态管理：存模型当前的状态，参数变更后通知几何层重建。
这样的好处是，以后哪怕想换掉 OpenCascade 换成别的内核，渲染层和特征层都不用动。这种面向未来改动的设计，值得多花点时间。
在类型定义上，我建议不要把 OpenCascade 的类型散落各处，统一在oc.d.ts里声明。因为 OpenCascade.js 的 API 是 C++ 绑定，类型复杂，参考官方声明自己补一层薄封装，能让同事少加班。
5.2 我踩过的几个坑
这几年实践下来，印象最深的坑有四个。
第一个是 WASM 加载路径问题。早期我用本地开发服务器，wasm 文件可以正常加载，但部署到生产环境后，路径多了一层 base path，直接白屏。解决方案是封装locateFile时用固定 CDN 路径，而不是相对路径。
第二个是原生对象生命周期。OpenCascade 的 shape 对象不是 JS 垃圾回收管理的，必须手动释放。曾经有个版本我没释放临时体，连续做 50 次布尔运算后浏览器内存飙到 2GB，卡死。后来我严格使用try/finally释放，内存峰值降到 300MB。
第三个是方向向量容易写错。创建圆柱时gp_Ax2的方向一旦方向不对，圆柱体可能饶了反轴。有一次我把(0,0,1)误写成(0,0,-1)，结果生成的孔反了，废了半天发现只是方向问题。
第四个是浏览器兼容性。WebGL2 基本普及，但老版本 Safari 对InstancedMesh和computeVertexNormals的支持有细微差别。建议用renderer.capabilities.isWebGL2做能力检测，给出降级提示，别让用户白屏。
5.3 后续还能怎么扩展
浏览器里的实体建模空间还很大。现在最让我兴奋的方向有三个：
一是把 AI 加进来。通过 MCP 协议，让 AI 助手理解用户的自然语言，在特征树层面驱动参数，而不是直接操作网格。这一步做好了，建模工具就不再只是绘图板，而是设计助手。
二是做多人协同。传统 CAD 的单机模式已经跟不上远程协作需求。在浏览器里基于 WebSocket 同步参数化特征树，实现两人同时编辑一个模型，OpenCascade 只负责计算，服务器做状态同步，架构上完全可行。
三是接入沉浸式交互。WebXR 设备的浏览器支持正在变好，如果能够在三维空间里直接用手势或空间控制器做拉伸、旋转，会大大降低三维设计门槛。
根据我个人的体会，浏览器实体建模最大的价值，不是取代桌面 CAD，而是把设计能力从“少数专业软件”里解放出来，放到网页、放到协同工具、放到教学课堂里。它离“人人可建模”更近了一步。最后分享一个小技巧：做任何浏览器三维工具，都记得在开发阶段开一个调试面板，实时显示 WASM 内存占用和网格三角形数量。这两个数字一个反映计算健康度，一个反映渲染压力，能看到它们，你就不会在性能泥潭里摸索太久。
这些实践经验未必每个都能直接套用，但基本都是真金白银踩出来的。Solid Modeling in your Browser 这条路还年轻，但底下的技术地基已经完全打得住了。如果你也正在做类似的探索，希望这篇能帮你少走几段弯路。
