资源雷达：UUID 引用与依赖分析器

Creator 3.x
#1 

`[uuid_lookup](https://store.cocos.com/app/detail/8177)` 是一个面向 Cocos Creator 项目的资源查询与引用排查插件。它可以通过长 UUID、短 UUID、资源名、资源路径或当前选中资源快速定位资源，并查询该资源被哪些场景、预制体、动画、材质、字体、粒子、JSON、Spine/DragonBones、FBX 等文件引用。

## 支持环境

- 平台：macOS、Windows
- Creator 2.4.x：推荐 2.4.5 - 2.4.15
- Creator 3.x：已适配 3.8.x，其他 3.x 小版本可按实际编辑器 API 情况测试
- 可安装到项目插件目录，也可安装到全局插件目录

## 一句话介绍

当你只知道一个 UUID、一个资源名，或者想在删除/重构资源前确认它到底被哪里使用时，这个插件可以直接给出资源路径、UUID、引用文件、节点路径、组件和属性，并支持一键打开、定位、复制和继续追踪引用链，而且查询速度超快。

## 核心功能

- 资源查询：支持长 UUID、短 UUID、资源名、资源路径、当前选中资源查询。
- 引用查询：查询资源被哪些场景、预制体和其他资源引用。
- 精准定位：场景/预制体引用可尽量定位到节点、组件和属性。
- 资源操作：高亮资源、打开资源、定位文件夹、复制长/短 UUID、删除资源。
- 右键菜单：资源管理器中可直接查询引用；Inspector 组件三点菜单可打开脚本或查询脚本引用。
- Button 辅助：`cc.Button` 可直接打开 Click Events 绑定脚本，并按配置复制绑定方法名。
- 脚本移动修正：在资源管理器中拖动脚本或脚本文件夹后，自动更新项目内相对 `import` / `require` 路径。
- 脚本依赖扫描：可选扫描脚本中的 `import` 引用，补充场景和预制体之外的代码依赖关系。
- 最近打开：记录并展示最近打开的场景/预制体。
- 外部联动：提供本地 HTTP `/open` 入口，方便日志、检查工具、后台页面点击后跳转到 Creator。
- 大项目优化：资源类型索引、缓存、批量处理、多引用折叠、仅扫描场景/预制体等选项降低查询成本。

## 安装与版本切换

插件内置 `package.v2.json` 和 `package.v3.json` 两套模板，执行 setup 后会生成当前 Creator 版本需要的 `package.json`。

Creator 2.4.x：

```bash
COCOS_CREATOR_VERSION=2.4.15 npm run setup

Creator 3.8.x：

COCOS_CREATOR_VERSION=3.8.8 npm run setup

执行后重启 Creator，或在扩展管理器中禁用/启用插件。

基础使用

  1. 打开插件面板。

    • 2.4.x：顶部菜单或插件面板入口打开 UUID 查询工具。
    • 3.x：顶部菜单 UUID 查询工具 -> 打开面板。

  2. 输入查询内容。

    • 长 UUID：0862dd0f-cd2e-46e9-936c-919c5ac97ab5
    • 短 UUID：0862d0PzS5G6ZNskZxayXq1
    • 资源名：coin
    • 路径：db://assets/resources/coin.prefab
    • 输入框留空：查询资源管理器当前选中资源

  3. 点击 查询，或选中资源后按 F5。

  4. 在结果中继续操作。

    • 高亮：在资源管理器中定位资源。
    • 打开：打开场景、预制体、脚本、图片等资源。
    • 查询引用：查找哪些资源引用了它。
    • 定位文件：在 Finder/Explorer 中显示资源文件。
    • 删除：删除资源，适合确认无引用后清理。
    • 复制：复制长 UUID 或短 UUID。

引用查询

查询引用后，插件会尽量把结果解析为更贴近业务的形式：

assets/resources/coin.prefab
节点: Canvas/Icon -> [组件] cc.Sprite -> [属性] spriteFrame

引用结果支持：

  • 高亮：高亮引用所在资源。
  • 打开：打开引用所在场景或预制体。
  • 定位：定位到具体节点。
  • 查询引用：继续追踪引用链。
  • 多引用折叠/展开：一个文件里多处引用会合并显示。

设置中的 引用仅查场景/预制体 建议日常开启，速度更快、结果更聚焦。需要排查动画、材质、字体、粒子、JSON、Spine/DragonBones、FBX 等间接依赖时，再关闭该选项做深度扫描。

如果需要把脚本依赖也纳入查询结果，可打开 包含脚本 import 引用。该选项适合重构脚本、移动目录或删除公共工具前确认代码依赖；日常只查场景和预制体时可以保持关闭。

拖动脚本后自动修改 import

资源管理器中移动脚本或脚本文件夹时，插件默认会自动扫描 assets 下的 JavaScript/TypeScript 文件，并修正受影响的相对路径：

// 移动前
import { formatCoin } from '../old/coin';

// 将 coin.ts 拖到 new/coin.ts 后
import { formatCoin } from '../new/coin';

使用说明：

  • 设置中默认开启 拖动后自动改 import；关闭后移动资源不会改写代码。
  • 支持移动单个 .js / .ts 文件，也支持移动包含脚本的文件夹。
  • 会处理相对 import、require() 和 XML reference path；非相对路径（例如包名、别名、远程模块）不会改动。
  • 修改会直接写回脚本文件。移动完成后建议查看编辑器日志，并运行一次项目构建或类型检查。
  • 只修正能解析到实际文件的路径；动态拼接路径、配置生成路径等情况仍需手动检查。

右键与 Inspector 工作流

资源管理器：

  • 右键资源 -> UUID 查询工具/查询引用。
  • 面板空输入点击查询或按 F5 可查询当前选中资源。

Inspector 组件三点菜单：

  • 自定义脚本组件：追加 open Component 和 脚本引用查询。
  • cc.Button：追加 打开点击脚本。

打开点击脚本 会尝试解析 Button 的 Click Events，打开绑定的自定义脚本；如果设置中开启 复制点击方法名，会同时复制 handler 名，便于在代码编辑器里快速搜索。

最近打开

最近打开 标签会显示最近打开的场景和预制体。可以直接打开、高亮、复制 UUID 或查询引用。

  • 2.4.x：结合编辑器 recent-items/local 记录。
  • 3.x：插件维护 settings/uuid_lookup.json 中的 recentOpenedAssets，并周期同步当前场景/Prefab 状态。

外部 /open 入口

插件启动后会监听本地端口，默认：

http://127.0.0.1:2505/open

常见用法：

http://127.0.0.1:2505/open?uuid=0862dd0f-cd2e-46e9-936c-919c5ac97ab5
http://127.0.0.1:2505/open?query=coin
http://127.0.0.1:2505/open?path=db://assets/resources/coin.prefab

2.4.x 还兼容 fileid 参数，并支持 projectPath、projectName 校验，避免多个项目同时打开时定位到错误项目。端口被占用时可开启自动递增，也可以在面板中点击 切换到2505 让当前项目重新占用固定端口。

适合场景

  • 根据报错 UUID 找到真实资源。
  • 删除资源前确认是否仍被使用。
  • 查某个 prefab、图片、脚本挂在哪些场景或节点上。
  • 排查 UI Button 绑定了哪个脚本方法。
  • 大项目中清理无用资源、拆 bundle、做资源影响范围分析。
  • 外部日志/工具点击 UUID 后自动跳转 Creator。