二次开发一套浏览器端 3D 虚拟世界，先动这五处：改动面小、看得见结果
3D虚拟世界二次开发、浏览器端3D开发、three.js项目接手、3D虚拟世界源码、GLB模型优化、LOD分级、骨骼动画重定向、自部署3D、可二次开发3D场景、创世genesis
拿到一套陌生的工程，第一个问题通常不是"我要怎么加功能"，而是"我从哪儿下手不会把它弄坏"。
前者是产品问题，后者是工程问题。而大部分项目卡在后一个问题里——不是没想法，是改了三处之后世界打不开了，然后花两天回滚，热情就没了。
这篇写给准备在现成底座上做二次开发的人：独立开发者、接单的技术方、企业里被派来接手的前端。讲三件事：
- 为什么应该先改"看得见的那一层"，而不是先读代码
- 五个改动点，每一个改完会牵动什么、风险在哪
- 改坏之后怎么回得去
先交代我们是谁：创世Genesis（即创世虚拟世界CRM系统，同一个自部署 3D 虚拟世界产品）是一套浏览器端 3D 虚拟世界基座。源码开放（source-available），本地跑不花钱；要联网、要商用、要联邦，需要订阅授权。 准确条款在仓库 LICENSE / EULA 里。
这篇讲三件事
- 二次开发的第一步不是读代码，是改一处能立刻看见结果的东西
- 五个改动点，按"改动面 / 影响面 / 出事时看不看得见"排序
- 回滚机制和验收脚本：让"改坏"变成一件便宜的事
一、为什么先改"看得见的那一层"
一套 32 万行量级的工程，通读一遍的成本高到没人真的会通读。真实的接手方式是这样的：找一个入口，改一点，跑起来看，再往下走一层。
所以第一件事不是理解全局，是建立反馈回路——改一处，刷新，看见变化。这个回路一旦建起来，后面每一层都是它的延伸；建不起来，读再多代码也只是在脑子里堆零件。
这里有个容易被忽略的差别。空白工程里，你没有参照物。 你想加一个"点击物体弹出说明"，得先自己搭一个能跑的场景、一个射线拾取、一个弹层——在你能验证"加得对不对"之前，已经写了三天的前置代码。而在一套已经在跑的工程里，同类功能大概率已经有一处实现，你照着它改，改错有对照。这件事对人是这样，对 AI 编码工具也是这样：AI 能帮上多少忙，取决于项目里有没有可参照的现成实现。
下面五处，就是按"改动小、反馈快、出事看得见"这个顺序排的。
二、五处改动点，按风险从低到高
| 顺序 | 改什么 | 在哪改 | 牵动什么 | 风险 |
|---|---|---|---|---|
| 1 | 站点名称、欢迎语、界面文案 | 配置与语言文案层 | 不碰逻辑 | 低 |
| 2 | 初始场景内容、出生点、初始视角 | 浏览器端编辑器里拖 | 场景数据，不碰代码 | 低 |
| 3 | 模型与资产 | 资产入库（优先 GLB / GLTF） | 资产管线：体积、贴图、分级版本 | 中 |
| 4 | 角色外观与动作 | 骨骼映射与动画配置 | 跨来源骨骼兼容、动画重定向 | 中 |
| 5 | 界面面板与交互按钮 | 前端 UI 层 | 与后端字段的对应关系 | 中高 |
上图是浏览器端 3D 编辑器：左边模型库、中间场景视口、右边对象列表与属性面板。第 2 处改动就发生在这个界面里，不用写代码。 把它放在第一位讲，是因为它是整条反馈回路里最短的一段——拖一下，刷新，看见。
第 1 处：改名字和文案。 看起来最没技术含量，但它的价值是让你确认一件事：你知道自己改的文件，到底有没有被加载。 很多人第一次接手项目，改完刷新没变化，以为是缓存，最后发现改的是另一个目录下的同名文件。这一处改动就是用来排除这个问题的，成本几分钟。
第 2 处：改场景。 编辑器里摆物体、调位置、定初始视角。这一层的关键不是"能不能摆"，是出生点和初始视角决定访客第一眼看到什么。同一个世界，出生点正对着一堵墙和正对着开阔处，是两个产品。这里不用写代码，但需要有人做审美判断——这是设计活，不是工程活。
第 3 处：换模型。 这是第一处会撞上真实成本的地方。出图用的模型和上网页的模型目标不同：前者要渲染出来好看，后者要在别人的网络和手机里跑得动。所以这一层的动作不是"把模型拖进去"，而是过一遍资产管线——转成 GLB / GLTF、压贴图、生成分级版本。仓库里这套管线是可复现的：贴图能压到原来的三成左右而几何不动，同一批资产生成三档 LOD，低模档的模型面数控制在百面以内（验收脚本跑出来是 118/118 达标）。这些数字你可以自己跑一遍对照，不要直接套到你手上那批模型上——不同来源的模型，压完的结果不一样。
第 4 处：换角色、加动作。 这里的坑不在代码，在骨骼。角色模型来自 Mixamo、Ready Player Me、VRoid、RootMotion 这类工具链时，骨骼命名和层级都不一样。仓库里对四类来源做过兼容验收，结果是 67/67 通过——这意味着你换角色时大概率不用重做骨骼。但如果你的角色来自第五个来源，就要自己验一遍，别假设它能用。
第 5 处：改界面。 界面是最容易改、也最容易改坏的一层，原因是它和后端字段绑在一起。改一个按钮的位置没事，改一个字段的含义会连带影响数据。到这一层，建议先把"这个字段谁在写、谁在读"弄清楚再动。
上图是编辑器的属性面板与对象列表。放在这里是想说明第 5 处的界限：面板上这些可调的项，是产品已经定义好的；你要加一个全新的属性，就不是"改界面"，而是往后端和存储层各加一节——那已经是第六处了。
三、第六处：真正属于你的那一层
上面五处改完，这个世界看起来是你的了，但它还不是你的产品。
真正属于你的东西在第六处：你自己写的业务层。 比如一个设备目录、一套课程表、一个展品的讲解规则、一个内部审批流。它落在底座之上，通过接口跟世界交换数据。
这一层怎么起，取决于你的业务形态，没有通用答案。但有一个判断标准可以用：如果你的改动需要动到底座内部的实现，那说明它在第五层之下，不是你的业务层。 这个界限清楚，后面升级底座的时候才不会每次都重来一遍。
四、改坏了怎么回去
二次开发里"改坏"是常态，不是事故。真正决定你能不能持续做下去的，是改坏的代价有多低。
| 做法 | 作用 | 成本 |
|---|---|---|
| 一次只改一处，改完立刻验证 | 出事时能定位到具体那一处改动 | 每次多花几分钟 |
| 用 git 分支做实验 | 改坏了整条分支丢掉，不影响主线 | 学一次 |
| 先跑仓库里的验收脚本 | 用脚本给出的实测值判断，而不是凭感觉 | 跑一遍的时间 |
| 先保证"能进"，再追"好看" | 顺序反了会在最脆弱的时候动性能 | 无 |
仓库里带了一批验收脚本（scripts/accept_*.js 这一类），覆盖的是可以量化的部分：绘制调用数、资产体积、骨骼兼容、断线重连、LOD 达标情况。它们的价值不是证明程序好，是给你一个改动前后的对照基线。 你改完跑一遍，数字变了多少，比"感觉好像快了一点"可靠。
还有一个习惯值得早养成：先改到"能进"，再改"好看"。 很多人反过来——先把光照和材质调到满意，最后发现掉帧，然后在最不好改的时候去动性能。
五、AI 编码工具在这条线上的位置
这一类工具现在确实能接上一套陌生工程，前提是工程本身可读。这里只讲三条边界，因为它们决定了你能不能用得放心：
- 它省的是"读懂陌生工程"的时间，不是"装环境"的时间。 Node 版本、数据库、端口、域名备案，这些还是要人来。
- 它写的代码仍然要人审。 它知道你的代码，不知道你的业务规则——比如"这个字段在你们公司代表含税还是不含税"，它猜不出来。
- 第五层之上的判断仍然是人做。 它是加速器，不是替代品。
一个具体的用法，比"让它帮我写个功能"有效：先让它解释现有那处实现的调用链，再让它按同样的模式改。 前者是让它读，后者才是让它写。跳过第一步直接写，产出的东西往往跟你项目里已有的做法不一致。
六、这个方向不适合什么
- 想换渲染核心或改引擎。 那已经不是二次开发，是重写。底座的价值恰恰在于你不用碰这一层。
- 需要跟企业现有系统做深度双向同步。 这是后端集成工程，不是改前端界面能解决的。它需要单独设计，工期也要单独算。
- 团队里没有人愿意读代码。 二次开发的前提是有人能读、能判断。全部交给外部，你会在第一次要改的时候发现没人能验收。
- 只是想放几张产品图或者一段视频。 那不需要 3D。图片和视频更便宜，也更稳。
七、边界与未实测
如实写在这里：
- 手机端帧率与耗电未做完整实测。 手机能进、能逛是验证过的，具体表现要以你的目标机型为准。
- 本文没有可引用的耗时数字。 我没有实测过"改完这五处要几天"这种事，也不编一个。这五处是路径，不是工期承诺。
- 文中技术数字来自仓库里可重跑的验收脚本（贴图压缩、LOD 达标、骨骼兼容 67/67、绘制调用治理），你可以自己跑，但不要直接套到别的资产上。
- 规划项未实现：AI 拼装世界、Agent 商店、Agent 互操作、跨世界联邦 AI。它们是路线图上的东西，不是现有功能。
- 截图为写作时版本的实机画面，界面会随版本演进。
- 我们不提供定制开发服务。 这篇是接手路径，不是服务介绍。
八、常见问题
问：我先读代码还是先跑起来？
先跑起来。跑不起来，读代码读到的是纸上的东西；跑起来之后，你改一处能立刻验证，理解速度完全不一样。
问：五处里哪一处该先做？
第 1 处。它几乎不花时间，但能帮你确认改的文件真的被加载了。这个前提不成立，后面全是白工。
问：模型一定要转 GLB 吗？
浏览器端优先 GLB / GLTF，这件事在导出那一步就该定。如果源头是别的格式，转换是一块独立工作量，不要当成顺手的事。
问：我怎么知道改动有没有伤到性能？
改前跑一遍验收脚本记下数字，改后再跑一遍。绘制调用、资产体积这两个数字变化最敏感。
问：世界跑起来之后，我要改的东西和底座版本升级冲突了怎么办？
冲突集中在第五层之下。这也是为什么上面要划那条线：你自己的业务层不碰底座内部，升级时就能整块替换。
九、源码与仓库
三个地址内容一致，国内访问用前两个更快。仓库里有部署说明和一批验收脚本，可以自己跑一遍看实测值。
- Gitee（国内访问更快）：https://gitee.com/miduoxinxijeji/miduo.git
- GitCode（国内镜像）：https://gitcode.com/qq_35054471/virtual-world
- GitHub：https://github.com/miduo100/3d-virtual-world
关于创世Genesis
创世Genesis是一套基于Three.js+WebGL构建的自部署3D虚拟世界系统，帮助个人与企业搭建属于自己的3D空间。浏览器直接访问，PC和手机双端兼容，支持多人在线、联邦传送、商铺系统，并支持Agent接入——AI能以具身角色进入你部署的世界。数据运行在你自己的服务器上，不经过第三方平台——让每个世界都真正属于它的主人。
先改一处能立刻看见结果的东西，比先通读代码更快进入状态。 创世Genesis（创世虚拟世界CRM系统）是一套浏览器端 3D 虚拟世界基座——底下几层已经在跑，上面那一层留给你写。如果你通过「创世Genesis」没搜到我们，直接搜「创世虚拟世界CRM」即可。
关于名字：本文说的创世Genesis，即创世虚拟世界CRM系统，两者是同一个自部署 3D 虚拟世界产品。若你通过「创世Genesis」没搜到我们，直接搜「创世虚拟世界CRM」即可。