three-devtools 源码开发指南：从本地调试到 Chrome 网上应用店发布的完整教程
【免费下载链接】three-devtoolsthree.js devtools项目地址: https://gitcode.com/gh_mirrors/th/three-devtools
three-devtools是一款面向 three.js 的浏览器开发者工具扩展（three.js devtools），能在 DevTools 中可视化检查 3D 场景、渲染器、材质与纹理，并支持直接修改参数。本文是一份从零开始的源码开发指南，带你完成环境搭建、本地调试、构建打包，最终把扩展发布到 Chrome 网上应用店（Chrome Web Store）与 Firefox 附加组件商店的完整流程。
🧭 先认识项目：它是什么
three-devtools 以"面板（Panel）"的形式嵌入浏览器开发者工具中。打开一个运行 three.js 应用的页面后，你可以在three标签页里：
- 🌐 浏览场景对象树（Scene Graph）
- 🎨 查看并实时修改材质、几何体参数
- 🖼️ 预览纹理（漫反射、法线、粗糙度等 PBR 贴图）
- ⚙️ 调整渲染器与相机参数
下面的示例场景就来自项目自带的演示页，打开开发者工具即可用 three-devtools 检查其中的网格、材质与纹理：
项目官方说明文档：DEVELOPMENT.md、README.md
🚀 一键安装：克隆仓库并安装依赖
只需 3 条命令即可开始：
git clone https://gitcode.com/gh_mirrors/th/three-devtools cd three-devtools npm install依赖项定义在 package.json 中，核心依赖包括lit-element（Web Components UI 框架）、three0.137.0（内置一份私有的 three.js 用于注入可视化）、webextension-polyfill（统一 Chrome/Firefox 扩展 API）。
🔍 本地调试：最快上手方法
Chrome：以"已解压扩展"方式加载
- 打开
chrome://extensions，开启右上角"开发者模式" - 点击加载已解压的扩展，选择项目根目录
- 出现一条关于
browser_specific_settings的警告属正常现象，可忽略（这是 Firefox 专用的 manifest.json 字段） - 访问任意 three.js 页面（可运行自带示例 examples/objects.html），打开开发者工具即可看到three面板
Firefox：用 web-ext 自动调试
npx web-ext runweb-ext会启动一个带扩展的 Firefox 实例，改完 src/app/ 的界面代码后刷新面板即可看到效果。
⚡ 调试刷新规则（重要）
| 修改的文件 | 需要做什么 |
|---|---|
| src/app/（面板 UI） | 刷新 DevTools 面板即可 |
| src/content/（注入脚本） | 在chrome://extensions重新加载扩展 + 刷新页面 |
| src/extension/（通信管道） | 重新加载扩展 + 刷新页面 |
📂 目录结构：源码都藏在哪儿
src/ ├── app/ # DevTools 面板前端（Web Components + LitElement） ├── extension/ # 通信管道：content script / background / devtools 三端脚本 └── content/ # 注入到用户页面上下文、直接接触 three.js 实例的脚本 web_modules/ # 预构建的依赖模块（由 @pika/web 生成） examples/ # 自带演示场景 scripts/ # 构建与发版脚本关键文件速查：
- 面板入口：src/app/index.html 与 src/app/index.js（注册所有自定义元素）
- 根状态元素：src/app/elements/AppElement.js，负责整个应用状态与重渲染
- 注入侧单例：src/content/ThreeDevTools.js（observe / select / update 等核心 API）
- 通信三端：src/extension/contentScript.js → src/extension/background.js → src/extension/devtools.js
- 数据序列化：src/content/toJSON.js（把 three.js 对象转成面板可渲染的数据）
🔄 理解数据流：消息如何跨越 4 个上下文
这是理解源码最关键的一张"心智地图"。three.js 场景数据必须穿越4 个上下文：
- 注入脚本（src/content/，运行在页面用户上下文，能摸到 three.js 对象）
- Content Script（src/extension/contentScript.js，通过
postMessage中转） - Background（src/extension/background.js，按
tabId把消息转发给对应面板） - DevTools 面板（src/app/，前端应用渲染）
而反方向（面板 → 页面）走得更直接：面板通过chrome.devtools.inspectedWindow.eval()直接在用户上下文执行命令，例如选中某个对象、修改某个数值。之所以要设计这么"绕"，是因为纹理等大数据（base64 字符串）走 eval 轮询会严重卡顿，只能走 port 消息通道。
页面接入也很简单，three.js 应用只需注册场景与渲染器：
if (typeof __THREE_DEVTOOLS__ !== 'undefined') { __THREE_DEVTOOLS__.dispatchEvent(new CustomEvent('observe', { detail: scene })); __THREE_DEVTOOLS__.dispatchEvent(new CustomEvent('observe', { detail: renderer })); }📦 构建打包：3 个 npm 脚本要分清
构建命令定义在 package.json 的 scripts 中，实际逻辑在 scripts/build-dist.sh：
| 命令 | 用途 |
|---|---|
npm run build:deps | 用 @pika/web 重新生成 web_modules/（升级依赖后才需要） |
npm run build:dist | 打包通用 zip（Firefox/非 Chrome 浏览器） |
npm run build:dist:chrome | 打包 Chrome 专用 zip（自动移除browser_specific_settings字段） |
npm run build:source | 打包未构建的源码zip，供 AMO 源码审查使用 |
💡 为什么 Chrome 要单独构建？因为 Chrome 不认识 manifest 里的
browser_specific_settings键，脚本会先删掉该字段再打包，消除警告。
🏷️ 版本号管理：一条命令同步所有文件
npm version patch # 或 minor / major这条命令会同时更新 package.json 与 manifest.json 中的版本号（由 scripts/version.js 完成），并自动打 git tag、推送到远端。发布前务必先执行这一步。
🌍 发布到 Chrome 网上应用店（Chrome Web Store）
完整发布流程：
- 双端自测：
npx web-ext run测 Firefox；chrome://extensions加载已解压测 Chrome - 提升版本号：
npm version minor - Chrome 专用构建：
npm run build:dist:chrome，产物在dist/目录 - 上传：登录 Chrome 开发者后台（Chrome Developer Dashboard），找到 Three.js Developer Tools 条目，点击编辑，上传
dist/three.js_developer_tools_*.zip - 等待审核：由于扩展申请了
http://*/*与https://*/*等宽泛权限，审核时间会稍长，接受审核提示即可
🔥 顺便发布到 Firefox AMO
npm run build:dist生成主构建，npm run build:source生成源码包- 登录 AMO 开发者后台，上传
dist/three.js_developer_tools_*.zip - 因使用 @pika/web 打包了依赖，按 AMO 源码提交政策还需上传
dist/three-devtools-source.zip
🧰 新手常见坑位清单
- 改完 src/content 没效果？这类脚本是注入到用户上下文的，必须重载扩展并刷新页面
- 注入方式为什么"奇怪"？Content Script 拿不到页面 JS 全局变量，所以 contentScript.js 会动态插入
<script>同步注入window.__THREE_DEVTOOLS__，让页面代码尽早可注册 - 依赖变了要重新 build:deps 吗？要。web_modules/ 是预构建产物，
package.json依赖更新后执行npm run build:deps重新生成 - 想跑示例场景？项目自带 examples/ 下的多个演示页（scenes.html、materials.html、large-data.html 等），
npm run serve后浏览器打开即可
✅ 小结
- 三步起步：克隆 →
npm install→chrome://extensions加载已解压 - 数据流记住"4 上下文"：注入 → content script → background → 面板
- 发布前必做：双端自测 +
npm version+build:dist:chrome - Chrome 上传 zip 到开发者后台即可，Firefox 另需提交源码包
掌握这条从本地调试到 Chrome 网上应用店发布的完整链路，你就能独立迭代 three-devtools 这个 three.js 3D 开发工具了。祝开发顺利！🚀
【免费下载链接】three-devtoolsthree.js devtools项目地址: https://gitcode.com/gh_mirrors/th/three-devtools
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
