SuperSplat 高斯泼溅编辑 3 坑排查指南

【免费下载链接】super-splat3D Gaussian Splat Editor项目地址: https://gitcode.com/gh_mirrors/su/super-splat

在浏览器里直接做 3D Gaussian Splat 编辑的人，多半会先碰到 SuperSplat。真正卡人的很少是渲染，而是依赖装不上、本地服务起不来、PLY 文件加载报错这三处。

SuperSplat 是什么

SuperSplat 是为 3D Gaussian Splat 而生的开源编辑器，浏览器直开、零安装，WebGL 与 WebGPU 双渲染，拖入 .ply 即可查看、变换、裁剪、保存。

🧭 快速自检清单

• npm install一报错 → 先查 Node 版本，项目要求 20.19 以上
• npm run develop起了但页面打不开 → 3000 端口被旧进程占了
• .ply 加载报错 → 文件里可能根本没有高斯泼溅数据
• 加载后内存暴涨 → 球谐数据太多，先裁剪再加载

🔧 依赖装不上的最快修法

npm install 报错，按这个顺序修

SuperSplat 安装失败的人，多半卡在这一步，而且卡住就动不了。先看报错文本：写的是 Node 版本不支持，那就是最常见的原因——项目要求 20.19 以上，升级完再跑npm install。版本没问题还报错，把 npm 缓存清一遍（带 force 选项）再装。还不行，node_modules 整个目录连同 package-lock.json 一起删掉，从头装。这步别偷懒，多数诡异报错到这就消了。再不行，把终端完整输出贴去社区问，一定有人踩过同样的坑。

📦 本地服务起不来的排查顺序

npm run develop 跑了，浏览器没反应

这步吃人的地方，是终端看着挺正常。其实挂的地方就两处。一查端口：提示 3000 被占用，就是上次开发进程没退，杀掉它或换个端口，再跑npm run develop。二查编译：rollup 输出里有报错，那挂的是构建而不是服务，照日志一条条修，多半是 TypeScript 或资源路径的问题。实在看不出，翻一下 package.json——develop 其实是监听加静态服务两个任务，分清哪个挂，问题就少一半。

SuperSplat 加载 PLY 报错，看这 3 点

文件拖进去就是加载失败

这步的坑比想象中隐蔽：SuperSplat 只认装着高斯泼溅数据的 .ply，普通点云或网格就算顶着 .ply 的名字，也加载不进来，官方文档第一句就在提醒这件事。按顺序来：先拿一个确定能用的样例加载，能开就说明问题在你自己的文件里，别怪工具。再换入口试：拖拽、Scene 菜单的 Open、URL 里加 load 参数，三条路都通。文件太大、加载后内存暴涨的，多半是球谐数据，先裁剪或导出压缩 ply 再加载。还不行，加载逻辑都在 src/io/read/loader.ts 里，带着它去社区提问，回得更快。

一句话收尾

三个坑说白了就三件事：版本、端口、数据格式。闯过去，本地开发基本就顺了。更深的用法去看官方文档，或者直接去社区问——你的报错信息，多半是别人解过的问题。

【免费下载链接】super-splat3D Gaussian Splat Editor项目地址: https://gitcode.com/gh_mirrors/su/super-splat