# Tree_3.x **Repository Path**: lxd_sun_admin/tree_3.x ## Basic Information - **Project Name**: Tree_3.x - **Description**: Cocos3.x 浏览器节点树插件 - **Primary Language**: HTML - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 3 - **Created**: 2026-09-26 - **Last Updated**: 2026-09-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ccc3-devtools v1.3.0 > Cocos Creator **3.x** 浏览器运行时节点树调试工具。 > 基于 [potato47/ccc-devtools](https://github.com/potato47/ccc-devtools) v2.3.1 改写，保留全部功能，针对 3.x 引擎 API 全面重写。 ## 它能做什么 - 实时查看游戏运行时的**节点树**（自动 / 手动两种刷新模式，可搜索、可拖拽） - 点选节点后**在线修改属性**：位置、旋转、缩放、锚点、UI 尺寸、颜色、透明度等 - 支持常用组件：Camera / Sprite / Label / UITransform / MeshRenderer / Button 的可视化编辑 - 一键**输出节点 / 组件引用**到浏览器控制台（`window.temp1`），方便二次调试 - 一键**标记节点位置**（绿色圆 / 红色矩形，自动消失） - **资源缓存面板**：浏览纹理 / SpriteFrame / Prefab / AnimationClip 等已加载资源，支持 Release - **Stats.js** 性能监视（FPS / MB / draw call 等） - **暗黑主题**（localStorage 记忆） - 控制台辅助命令：`cc.tree()` / `cc.cat(id|name)` / `cc.list(name)` - localStorage 自动记忆设置（节点树开关、暗黑主题、性能监视、面板显示状态） - toolbar 上自带 **Tree 按钮**，一键切换面板显示 / 隐藏（记忆状态） ## ⚠️ 重要：3.x 的预览模板机制跟 2.x 完全不同 | 维度 | 2.x | 3.x | |------|-----|-----| | 模板位置 | `/resources/static/preview-templates/` | **项目根目录**的 `preview-template/`（单数） | | 入口文件 | `index.jade` | `index.ejs`（`index.html` 优先级更高） | | 容器名 | `Cocos2dGameContainer` | `Cocos3dGameContainer` | | 引擎 API | `cc.loader` / `cc.js.getset` / `node._id` | `cc.assetManager` / `Object.defineProperty` / `node.uuid` | → **不要再往 Cocos 安装目录找 preview-templates 了**，3.x 起改为项目级。 ## 使用 ### 方式 0：一键部署（推荐）需要 Node 环境（Cocos Creator 自带，或系统自行安装）。在插件目录下执行： ```bash node install.js <你的Cocos项目根目录> # 或手动指定 Creator 版本 node install.js <你的Cocos项目根目录> D:\Cocos_editors\Creator\3.6.2 ``` 脚本会自动完成： 1. 读取项目 `package.json` 的 `creator.version`，优先匹配同版本的 Creator 2. 从 Creator 内置模板目录提取官方预览资源与 `index.ejs`（路径形如 `/resources/app.asar.unpacked/builtin/preview/static/`） 3. 创建 `<项目>/preview-template/`，复制官方资源（`index.css` / `favicon.ico` / `splash.png` 等） 4. 复制插件本体到 `<项目>/preview-template/ccc3-devtools/` 5. 在官方 `index.ejs` 里注入 include，生成最终模板完成后回到 Creator 刷新浏览器预览即可。若 `index.ejs` 已存在，会自动备份为 `index.ejs.bak-<时间戳>`。 ### 方式 1：手动部署 #### 第 1 步：在你的 Cocos 项目里生成默认预览模板打开任意 Cocos Creator 3.x 项目，主菜单 → **项目 → 生成预览模板**。这会在项目根目录下创建 `preview-template/`，里面有默认的 `index.ejs`、`index.css`、`favicon.ico` 等。 #### 第 2 步：把 ccc3-devtools 放进 preview-template/ 把整个 `ccc3-devtools` 文件夹复制到： ``` <你的项目根目录>/preview-template/ccc3-devtools/ ``` #### 第 3 步：在 index.ejs 里引入打开 `preview-template/index.ejs`，在 `` 里加一行： ```ejs <%- include ./ccc3-devtools/index.html %> ``` 最简改动版示例（节选）： ```ejs <%- include(cocosToolBar, {config: config}) %>

...

<%- include ./ccc3-devtools/index.html %>

<%- include(cocosTemplate, {}) %> ``` **或者**直接用本仓库提供的 [`index.ejs.example`](./index.ejs.example) 覆盖默认 ejs（基于 Creator 3.6.2 默认模板 + 已集成 ccc3-devtools，复制改名为 `index.ejs` 即可）。 #### 第 4 步：刷新浏览器预览刷新浏览器预览页面 → **左上角「节点树」悬浮按钮**（位于官方 toolbar 下方）→ 点击打开**左侧停靠面板**（面板贴浏览器最左边：上节点树 / 下属性面板，官方 toolbar 保持顶部通栏，游戏画面被挤到面板右侧）→ 点选节点即可在线查看 / 修改属性。**Esc** 或再点一次按钮即可关闭，游戏恢复全宽。面板每次刷新默认关闭（不记忆展开状态）；**暗黑主题默认开启**（只有显式在设置里关过才会用亮色，选择记忆到 localStorage）。 **组件属性面板为动态生成**：直接枚举组件的 CCClass 序列化属性（与 Creator 属性检查器同源），字段全量、同名同序——布尔出勾选、数字出输入框、颜色出取色器、向量按分量展开、引用/数组等复杂类型只读展示并支持「输出」到控制台（`window.tempN`）。 ## 文件结构 ``` ccc3-devtools/ ├── index.html # 插件主入口（ejs 子模板，无 html/head/body 外壳） ├── index.ejs.example # 完整 index.ejs 示例（基于官方模板 + 已集成） ├── install.js # 一键部署脚本（node install.js <项目目录>） ├── config.js # 节点 schema 配置（组件面板为动态生成，与 Creator 检查器对齐） ├── js/ │ └── app.js # 主逻辑（适配 3.x API + 悬浮「节点树」开关） ├── css/ │ ├── style.css # 基础样式 │ └── themes/ │ └── dark.css # 暗黑主题 ├── libs/ # 第三方库（与引擎无关，直接复用 2.x 原版） │ ├── vue/ │ ├── element/ │ ├── iview/ │ ├── vue-beauty/ │ └── stats/ ├── screenshots/ # README 引用的截图（沿用 2.x 原版） ├── 引用方式.txt # 详细集成步骤（含 3.x 与 2.x 机制对比） ├── version.json ├── LICENSE # 沿用 MIT License（与原版一致） └── README.md ``` ## 控制台辅助 API ```js cc.tree() // 打印当前场景完整节点树（折叠形式） cc.tree(nameOrIndex) // 从指定节点开始打印 cc.cat(index) // 按索引取节点 cc.cat('Player') // 按名字取节点（不区分大小写） cc.list('btn') // 名字包含 btn 的所有节点 ``` > 原 2.x 的 `cc.where()`（在 Canvas 上画标记框）已移除：它依赖 2D 模块的 > Graphics/UITransform，在裁剪过 2D 的构建里无法工作。 `outputNodeHandler` 按钮会把当前选中的节点存到 `window.temp1`、`window.temp2`... 便于在控制台进一步操作。 ## 与 2.x 原版的代码差异（核心改动点） | 2.x 原版 | 3.x 适配 | |---------|---------| | `cc.loader._cache` | `cc.assetManager.assets`（Map 结构） | | `cc.loader.release(id)` | `cc.assetManager.releaseAsset(asset)` | | `new cc.Color().fromHEX()` | `cc.Color.fromHEX()`（静态方法，可接受 hex 字符串构造） | | `node.color.toHEX()` | 自实现 `colorToHex(color)` 工具函数（3.x 的 `cc.Node` **已无 color**，颜色属于 Sprite / Label 等 UIRenderer 组件） | | `cc.js.getset()` | `Object.defineProperty()` | | `node._id` | `node.uuid` | | `node.__classname__` / `component.__classname__` | `.constructor.name` | | `node._onPreDestroy` 钩子 | `node.once('destroy')` 事件 | | `texture.url` | `texture.nativeUrl`（优先）/ `url`（兜底） | | `cc.find('Canvas')` | `scene.getChildByName('Canvas')`（更稳） | | `Cocos2dGameContainer` | `Cocos3dGameContainer`（兼容回退） | | 编辑器目录 `app/editor/static/preview-templates/...` | 项目级 `preview-template/ccc3-devtools/...` + 相对路径 | | 模板引擎 jade | ejs（`<%- include ./ccc3-devtools/index.html %>`） | | 无开关按钮，靠齿轮面板 | toolbar 上独立 **Tree 按钮**，一键切换显示/隐藏 | ## 已知问题 - **`ccc3-devtools/index.html` 里绝对不能出现 ejs 模板标签**（百分号加尖括号的写法）。它会被 ejs 当模板编译，出现标签就会报 `Unexpected token` 编译错误 - `preview-template/` 下若同时存在 `index.html` 和 `index.ejs`，**`index.html` 优先级更高**，Creator 会忽略 ejs。别在根目录放 `index.html` - 升级 Cocos Creator 大版本时 `preview-template/` 跟着项目走，不会被覆盖（这是 3.x 相对 2.x 的好处） - 但生成预览模板菜单可能更新默认 ejs，注意 merge 自定义改动 - 开启节点树会增加渲染开销，发布版本请删除 include 或注释掉 - 资源 Release 是危险操作，请确认依赖关系后再用 - 3.x 的部分 2D 组件（UITransform 之外的旧 UI）已弃用，本插件仅覆盖 3.x 推荐用法 - 自实现的 `colorToHex` 只支持 RGB（不输出 alpha）。如需透明度，请在面板用「Opacity」字段单独调 - 第一次使用可以跑 `node install.js <项目目录>` 一键部署；或手动在 Creator 菜单点 **项目 → 生成预览模板** - **【已修复的白屏坑，别改回去】** 2.x 原版在 `created()` 里会把 `#app` 挪到 `body` 首个子节点。3.x 的部署形态下 `#app` 是 `#dev-app`（面板外壳）的子节点，挪走之后 `#dev-app` 变成一个**空的白色全屏遮罩**（`z-index:99999`），打开面板就盖住一切 → 永久白屏且无法点击。`#app` 必须留在 `#dev-app` 内部 - **【已修复的重开坑，别改回去】** `doOpenDevMode()` 里不能用 `if (!cc.Node.prototype.isLeaf)` 判断是否已定义 —— 这会真的"读"一次 getter，而 getter 里的 `this` 是原型对象（原型上没有 `children`），直接抛 `Cannot read properties of undefined (reading 'length')`。第一次打开没事（属性还不存在），**第二次打开必炸**。要用 `Object.getOwnPropertyDescriptor()` 检查 - **【已修复的警告】控制台刷 `'BaseNode.childrenCount' is deprecated...`** ——这是 3.x 引擎把 `childrenCount` 标记为废弃导致的（`cocos/core/scene-graph/deprecated.ts`）。插件的节点树数据项就是 `cc.Node`，而面板默认用的 `vue-beauty` 的 `` 内部会读数据项的 `childrenCount`，因此每渲染一次就触发一批警告。插件已用 `shadowChildrenCount()` 在每个节点 **实例**上定义一个同名的非枚举属性来遮蔽（引擎那个 getter 因 `configurable: false` 无法在原型层覆盖，但实例属性可以遮蔽原型属性），并配有 1s 低频兜底扫描覆盖运行期 `addChild` 的新节点。若仍看到该警告，说明用的是 1.2.1 之前的版本 - **插件目录改名 / 换层级部署都不用改代码**：`app.js` 顶部的 `DEVTOOLS_BASE` 会从 `js/app.js` 自身的 `src` 反推出插件根路径，`version.json` 这类本地请求都基于它拼接。这样就不会再出现 `GET http://localhost:7456/version.json 404` ——那种情况是路径打到了预览页面根（`preview-template/`），而文件其实在 `ccc3-devtools/` 子目录里 - `vue-beauty` 的图标字体走的是外部 CDN（`at.alicdn.com`），完全离线/内网环境下控制台可能出现该域名的加载失败，属已知的非阻塞项，不影响面板功能 - **【1.3.1 修掉的静默失效字段】`config.js` 里的字段名必须是 3.x 真实存在的属性**，写错了不报错、只是"改了没反应"。已在 3.6.2 真实预览页逐项验过： | 组件 | 2.x 写法 | 3.x 真实属性 | 实测现象 | |------|---------|-------------|---------| | `cc.Camera` | `nearClip` | `near` | `typeof comp.nearClip === 'undefined'` —— 面板改了没反应 | | `cc.Camera` | `farClip` | `far` | 同上 | | `cc.Camera` | `ortho`（bool） | `projection`（ORTHO=0 / PERSPECTIVE=1） | `typeof comp.ortho === 'undefined'` | | `cc.Camera` | `clearFlags` 选项 0/1/2/3 | 位掩码：`SOLID_COLOR=7`、`DEPTH_ONLY=6`、`SKYBOX=14`、`DONT_CLEAR=0` | 真实相机是 14(SKYBOX)，旧列表里根本没有这个值；旧表选 SKYBOX 会往引擎写 2（=DEPTH），屏幕不清色 | | `cc.Camera` | 颜色 `rawField: 'color'` | `clearColor` | `color` 是 deprecated 别名，能用但**每次渲染都刷** `'Camera.prototype.color' is deprecated, please use 'Camera.prototype.clearColor' instead` | | `cc.Node` | `group` | 3.x 无此属性 | `typeof node.group === 'undefined'`，写了只是挂个野属性；3.x 可见性由 `layer` + 相机 `visibility` 位掩码决定 | 自定义 schema 时按这个套路自查：选中节点后在控制台 `typeof comp.你的字段`，出现 `undefined` 就说明字段名写错了 - **【已删除的死代码】节点级颜色桥接**：2.x 原版会在 `handleNodeClick` 里给节点挂 `hex_color` 桥接 `node.color`。3.x 的 `cc.Node` 没有 `color`，这段代码永远不会被读到。现在改成在注释里说明「节点配色请选中子组件改」，不再挂无用属性 ## 致谢 - 原版：[potato47/ccc-devtools](https://github.com/potato47/ccc-devtools)（MIT License） - 3.x 集成方案参考：[shengyihua/ccc-devtools3.0](https://github.com/shengyihua/ccc-devtools3.0) - Vue / Element-UI / iView / Vue-Beauty / Stats.js 等开源库 ## 协议本项目沿用原版 MIT License（见 LICENSE）。