跳到主内容

SolidCraft 源码怎么跑通:1.3 万星的开源 CAD,三条路三种代价

上周有人问我:那个一万多星的 SolidCraft,是不是 clone 下来 cargo run 一下就能用?我说不一定——它有三条完全不同的入口,选错一条,你会花一个晚上解决一个本来不存在的问题。装发行包的人被文件格式卡住,编译的人被两个 git 依赖卡住,图省事用浏览器版的人被 HTTPS 和 GPU 后端卡住。这篇把三条路的代价逐条摊开,你看完再决定走哪条。

先搞清楚它到底是个什么东西

SolidCraft 是纯 Rust 写的参数化 3D CAD,仓库在 tangency-labs/solidcraft,许可证是 MIT OR Apache-2.0。GitHub API 在 2026-11-04 零点实测:13,330 星、1,759 fork、语言 Rust、仓库体积 279,659 KB(约 273 MB),仓库创建于 2026-10-07,最后一次 push 是 2026-11-03 16:23。也就是说这东西不到一个月长到了一万三千星。

它和「CAD 查看器」最大的区别在于参数化时间线:你画草图、约束、拉伸、倒角,每一步都是一个特征,改一个参数,整条时间线重算。作者在 README 里给的验收口径很实在:76 个公开参考零件里,75 个的体积、面积、重心、包围盒与解析值或 FreeCAD 计算值对得上,剩下 1 个是已知 bug。这个数字比任何功能列表都可信,因为它承认了那一个对不上。

形态有四种,全跑在同一套命令上:桌面应用(Windows / macOS / Linux)、浏览器版(wasm + WebGPU/WebGL2)、headless CLI、还有 MCP server。README 里那句原话是「Everything the user can do is a command」——工具栏、对话框、脚本、CLI、MCP 走的都是同一批 command id。这个设计决定了它三条路线都能走通,也决定了我下面要讲的取舍。

顺带说个容易踩的:这个仓库以前挂在 bherbruck/solidcraft 名下,现在转到了 tangency-labs。老地址还能用,GitHub 会 301 过去(我实测 git ls-remote 旧地址返回了 HEAD),但Cargo.toml 里的 repository 字段至今写的还是老的 bherbruck 路径。所以你在网上看到两套 clone 地址都对,别以为是两个项目。

路线一:直接装发行包,代价是版本回不去

如果你只是想建个壳、导个 STL 去打样,装发行包就够了,别碰代码。这一点和我在 post/261 里写的判断逻辑一样:任务在一个界面里就能闭环、每天重复做的事固定,先装现成的,够用就别折腾自编译。

稳定版是 v0.30.1,2026-11-02 17:21 发布,一个 release 挂了 49 个资产。我把 Windows 相关的几个体积抄下来,因为这里有个反直觉的地方——同一版本两个安装器,体积差一倍:

资产字节数约合累计下载
solidcraft-0.30.1-windows-x64.msi84,287,48880.4 MB25,002
SolidCraft-0.30.1-windows-x64.exe172,718,280164.7 MB1,935
solidcraft-0.30.1-windows-x64-portable.zip106,138,114101.2 MB1,918
solidcraft-0.30.1-macos-universal.dmg230,007,447219.4 MB8,507
solidcraft-0.30.1-linux-x86_64.AppImage95,799,80091.4 MB4,444
SHA256SUMS.txt4,9104.8 KB10,706

下载量最高的是 msi(2.5 万次),排第二的是 macOS 的 dmg。那个 164.7 MB 的 exe 看体积像是带引导器的整包(我没拆包验证),而 msi 是常规安装包——需要离线分发或者塞进内网软件库的,选 msi,别看到 exe 就以为「exe 更原生」。同样,SHA256SUMS.txt 有 1 万多次下载,说明不少人真的在校验,这文件 4.8 KB,下载完顺手核一下比出事再查便宜得多。

第二个代价更要命:它的设计文件格式每隔一两个版本就升一次号,而且新版存的文件旧版打不开。发布说明里写得明明白白:0.28.0 是 format 45、0.29.0 是 46、0.30.0 是 47、0.30.1 是 48、0.40.0-rc.1 是 49。这不是「可能不兼容」,是「一定不兼容」。所以团队里几个人协作,版本号必须锁死;升级前先把手里在做的设计另存一份,这条比什么备份策略都实在。

还有两个小卡点,官方自己写在下载页上:Windows 的安装包还没有代码签名,SmartScreen 会拦,得点「更多信息」再点「仍要运行」;macOS 那个是签过 Developer ID 并且过了公证的,所以两个平台的体验不一致。另外从 0.11 到 0.14 这几个版本的用户要手动更新一次,应用内更新在那些版本上是断的。

路线二:从源码编译,代价在两个 git 依赖

要改代码、要交叉编译到别的平台、或者单纯想确认「这软件到底干了什么」,才值得走这条。前置条件官方写在 CONTRIBUTING 里,只有一句话,但信息量很大:stable Rust 1.95 或更新(egui/eframe 0.36 要求)。我打开 Cargo.toml 核了一下,workspace 里 rust-version = "1.95"、edition = "2024"、resolver = "3",三个都是新东西,老工具链会在第一行就报错。

我这台机器上装着 rustc 1.98.1,比门槛高三个小版本,理论上可以直接编。前置动作还有一个:把 MSVC 的 link.exe 加进 PATH(我这儿在 D:\soft\VSBuildTools\VC\Tools\MSVC\14.44.35207\bin\Hostx64\x64)——rustup 只管装 Rust,不管链接器,绝大多数「编译到最后一个 crate 才报 link.exe not found」都是这么来的。

然后我按官方三步走,卡在了第一步:

git clone --depth 1 https://github.com/tangency-labs/solidcraft
cd solidcraft
cargo build --release -p solidcraft-cli
cargo run --release -p solidcraft-cli -- commands

最后那行是官方给的自检动作:跑起来先打印命令注册表,能看到一长串 command id 就算通。第一次,21 秒后报:

fatal: unable to access 'https://github.com/tangency-labs/solidcraft.git/':
Failed to connect to github.com:443 after 21138 ms: Could not connect to server

换 HTTP/1.1 再来一次,报错变了样:fatal: fetch-pack: invalid index-pack output。第三次照原样直连,又是 21138 毫秒超时。中间我还试过 --filter=blob:none --no-checkout——克隆元数据只花 8.5 秒,看着挺顺,可 checkout 阶段要逐个补 blob,跑了 9 分 56 秒只下到 18 MB,只能停掉。

同一条网络路径下,crates.io 是通的:index.crates.io 返回 200 用时 0.73 秒,从 static.crates.io 取一个 crate 用 1.02 秒。github 的 codeload 也能连,就是速度只有 82 KB/s。所以问题不在「没网」,在 github.com 的批量传输这条路上。

这就是第二个问题的现场版:Rust 版本够、链接器也配好了,照样一步都走不动。别把「环境搭好」当成「能编译」——包管理器通(crates.io)和代码托管通(github.com)是两件独立的事,而后者恰好被那两个 git 依赖绑死在构建流程里,你想跳都跳不过去。

真正的坑不在编译命令上,在依赖图里。核心几何内核 solidcraft 依赖的 solidcore 与 solidcore-record,不是 crates.io 上的包,而是指向同一个 git 仓库 tangency-labs/solidcore 的两个不同 commit(8ddce901… 和 f5e8e9a2…)——同一个仓库,要按两个版本各拉一遍。这意味着 cargo build 过程中必须能连续访问 github.com 拉 git 对象。国内网络下这一步最容易断,而且断得很讨厌:不是一开始就报错,是编译十几分钟、卡在某个 crate 上才超时。

这跟我上次写 post/394 里那台数据库客户端的编译踩坑是同一个结论:关卡全在仓库外。代码本身没问题,卡你的是它依赖的外部路径。

官方给了绕法:在仓库外的 .cargo/config.toml 里写 [patch."https://github.com/tangency-labs/solidcore"],把 solidcore 指到你本地 clone 的路径。Cargo.toml 的注释里直接给了这行示例。所以正确的姿势是先把 solidcore 单独 clone 下来,再 patch 进来,而不是祈祷 cargo 一次性拉通。

另一个体积上的意外:仓库 273 MB,但工作区里的 vendor/ 目录被 exclude 排除在 workspace 之外。里面是三个打过补丁的 truck crate(truck 是上游的 B-rep 内核,Apache-2.0),只有 crates/kernel 允许碰它。这意味着你在 vendor 里改的东西不参与 fmt/clippy,也不会被 workspace 的测试覆盖——想改内核行为的人,先看清楚这条边界。

补一句编译目标怎么选,这里很容易一上来就选错。workspace 里有三个层级:-p solidcraft 是桌面应用,-p solidcraft-cli 是命令行,cargo xtask ci 是提交前全量(fmt、clippy、测试、图标、资源、分层检查、wasm)。按架构文档的分层说法,crates/ui-egui 是可替换的前端,桌面应用会把整条 egui + wgpu 渲染链拉进来;CLI 不碰 UI,只走 engine 的命令注册表,依赖树小一大截。想验证「这套工具链在我机器上能不能编」,先编 CLI 最省时间;要改界面,才轮到桌面版。别顺手敲 cargo build --workspace,那会把 wasm、文档和测试工具一起带上,多出来的时间和磁盘都不值。

顺手给个自测法,不用装任何东西:打开仓库的 Cargo.toml,搜两个词。搜 rust-version 看工具链门槛,搜 git = 看有几个 git 依赖。有 git 依赖,就先跑一句 git ls-remote <那个地址> HEAD 测通不通——我在本机测 tangency-labs/solidcore 用了 8.3 秒,返回一个 40 位 commit id,说明 ls-remote 这条链路是活的。但注意这只证明「问得到」,不证明「拉得下来」:我后面 clone 主仓库时三次全挂,就是活生生的反例。这一步 10 秒钟,能省掉一次二十分钟的失败编译。

路线三:不编译,用浏览器版加 CLI 和 MCP

第三条路最省事,也最容易被低估:浏览器版根本不用装,打开 solidcraft.io/app 就能建模型,URL 后面加 ?sample 直接开官方样例件。显卡或驱动不对劲导致画布黑屏的,加 ?webgl 强制走 WebGL2 后端。

但浏览器版有个硬限制,官方专门注了一句:保存和打开文件需要 HTTPS 或 localhost,因为它用的是 Origin Private File System。你把 trunk 起的服务绑到局域网 IP 上用 http 访问,页面能开、模型能建,就是存不了盘——这个现象特别容易被误判成「浏览器版是残废的」。

CLI 是单独发包的,比如 solidcraft-cli-0.30.1-macos-universal.zip(84,730,855 字节)。它的价值不在建模,在于把建模变成脚本:一个脚本就是一串 JSON 命令,solidcraft-cli run examples/bracket.json --out bracket.step 就能批量出 STEP。做参数化零件族、或者要把模型接进 CI 出图,这条路比 GUI 靠谱得多。

它的能力比名字唬人:run 跑脚本出 STEP,snapshot 出 PNG 预览(还能带 --tool Pin --section z=12 这种剖切参数),render 按渲染配置出产品图,eval 直接量一个导入的 STEP 文件。因为整套设计就是「用户能做的一切都是命令」,脚本等于把界面操作序列 JSON 化——你在窗口里点出来的每一步都能写成一行 JSON 存进版本库,下次改个参数重跑一遍。这是它和一般 CAD 命令行工具最大的区别:不是补了几个导出命令,是整套操作可编程。

MCP 是它最不一样的地方。桌面应用启动时默认就在 127.0.0.1:27878 开一个控制通道(端口被占就顺延),把实际端口写进 control/current.port,每次启动生成一个新 token,且只监听本机。所以 claude mcp add solidcraft -- solidcraft-cli mcp 之后,agent 能直接驱动你眼前开着的那个设计,你在屏幕上看它一步步建模。不想让它连,去偏好设置里关掉「Let AI agents connect」,下次启动生效。

这里有个细节值得单独说:--param-check off|warn|strict 三档,默认是 off。也就是说 agent 传错参数名(比如把 operation 写成 operaton)默认不拦,照样执行。要它拦,得显式设成 warn 或 strict。至于 MCP 协议本身的版本差异,我在 post/339 里捋过一遍——这个项目声明支持 2025-06-18、2025-03-26、2024-11-05 三个修订版,老客户端连上来是能通的,但工具语义按哪版走要自己对。

三条路横向对比:把代价摊在桌上

把上面三段压成一张表。注意「回退难度」这一列——它是最容易被忽略、又最容易在半夜咬你一口的东西。

路线你拿到什么前置成本首跑耗时主要卡点回退难度
装发行包可用的桌面应用下载 80–220 MB几分钟未签名被 SmartScreen 拦;格式升号低,但设计文件回不去
源码编译可改的完整工程Rust 1.95+、MSVC 链接器、能连 GitHub视机器,官方口径约 10 分钟两个 git 依赖拉不动高,273 MB 仓库加 target 目录都得留着
浏览器 + CLI/MCP零安装的建模与自动化一个支持 WebGPU 的浏览器秒级OPFS 要 HTTPS;GPU 后端可能黑屏无,刷新即可

怎么选:三个问题问完就有答案

第一个问题:你要不要动 crates/ 里的代码?不动,就别编译。这条能砍掉八成的编译需求。想改界面、改命令、加导出格式,才走路线二;只是想换个语言界面、调个快捷键,先去偏好设置里找,找不到再去提 issue。

第二个问题:你 build 的那一刻,能不能稳定访问 github.com?不能,就先 clone solidcore 做 patch,或者干脆走路线一。这不是技术能力问题,是网络路径问题,硬扛很浪费时间。

第三个问题:你需要 0.30.x 的稳定格式吗?需要,就别碰 0.40.0-rc.1。那个版本 2026-11-03 发布,把几何内核整个换成了 solidcore,设计文件格式是 49,存过之后 0.30.1 打不开;官方也明说它不进应用内更新检查,官网的浏览器版和 Flatpak 渠道都还留在原构建上。想试可以,另存一份再试。

还有一个判断,可能比上面三条都省时间:先看看你遇到的问题是不是项目自己已经知道了。这个仓库开放状态的 issue 与 PR 合计 5,462 条,而 issue 编号已经排到 11,675——这是不到一个月攒出来的。同时 CONTRIBUTING 里有一段很直接的声明:内核相关的工作已暂停,因为正在换新内核,所以布尔、倒角、抽壳、扫掠、STEP/IGES 导入导出、三角化这些方向的 PR 和 issue 一律先挂起,只有崩溃和数据丢失还会被受理。你倒角失败、布尔报错,大概率不是环境配错了,是它自己认了。搜 issue 时用 area:kernel 标签过滤,比按关键词瞎搜快得多。

最后一个反常识的旁证:有人真的把它编译到第三个平台去了。开源鸿蒙 PC 社区 2026-11-01 发了篇移植记录,基于 v0.25.1 做了个叫「轻星建模」的适配版,收录 3,251 个上游源码文件、约 97.1 MiB。作者把验收口径写得很硬:「不是编译通过,而是真机上可安装、可启动、可完成核心工作闭环」。他踩到的第一个坑是 surface 生命周期——重建必须先销旧,否则 GPU 状态残留会触发断言或者直接黑屏。这段话比任何编译教程都值钱:编译通过只说明代码能生成二进制,离能用还差一层平台适配。

常见问题

装完打开是黑屏,或者画布一片空白怎么办?先分清是哪个版本。0.30.1 的发布说明第一条就是修「浏览器版显示黑屏」这个 bug(issue #11107),所以浏览器黑屏先确认版本。桌面端如果控制台里有 WGPU error: Failed to create surface for any enabled backend,那是图形后端没起来,先更新显卡驱动;还不行就用浏览器版加 ?webgl 兜着,别在驱动上耗一晚上。

能不能在 Windows 上编译 Linux 版?方向反了。官方给的是从 Linux 交叉编译 Windows:cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft。反过来要 Linux 产物,最省事的是用它的 AppImage 或者直接走 Flatpak,不值得为这个搭交叉工具链。

我做好的设计能不能直接发给同事?能,但要对版本。文件格式每版升号、旧版打不开,所以发之前先问一句对方装的哪个版本。团队协作的稳妥做法是锁同一个版本号,或者导出成 STEP——STEP 是中性格式,不吃版本号,代价是丢掉参数化时间线,对方只能改实体不能改尺寸。

商用可以吗?要不要付费?它是 MIT OR Apache-2.0 双许可,二选一即可。仓库根目录同时放着 LICENSE-APACHE 和 LICENSE-MIT,Cargo.toml 里写的也是 MIT OR Apache-2.0;GitHub 侧栏只显示 Apache-2.0,那是双许可仓库的常见现象,不是许可证冲突。要注意的是它本身不提供任何担保,README 末尾有独立的免责声明,而且明确声明与 Autodesk、达索、PTC、西门子等厂商没有关联——你要拿它做商业交付,法务那关得自己过。

它是抄 Fusion 的吗?作者的态度写在 CONTRIBUTING 的第一条不可谈判规则里:行为只从公开文档、通用 CAD 惯例和用户反馈里设计,不驱动、不脚本化、不提取任何商业 CAD 产品的数据;第二条更狠——不许读 GPL/LGPL/AGPL 代码,连读都不行,所以 OpenCASCADE、FreeCAD(含 planegcs)、SolveSpace、CadQuery 全被排除在外。你可以不信这套说辞,但这个约束是真的写进了贡献规则的。

相关阅读

分享到:

本文链接:https://www.biyeyuanma.cn/post/400.html

服务热线

加我微信

加我微信