# @dcl/inspector 中文文档

规范地址：https://npmcn.com/package/%40dcl/inspector/

版本：7\.61\.2
npm 元数据更新时间：2026-11-09T17:20:56.000Z
中文译文更新时间：2026-11-11T17:31:00.813Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dcl/inspector
原文对照：https://npmcn.com/package/%40dcl/inspector/?lang=original
项目主页：https://github.com/decentraland/creator-hub#readme
源码仓库：https://github.com/decentraland/creator-hub

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：257 MB，1205 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2023-01-31T19:41:31.124Z
- 最新版本发布：2026-11-09T17:20:55.414Z
- 近 30 天下载量：17331（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：1033（近 12 个月 168 个）

## 中文简介

[![npm version](https://img.shields.io/npm/v/@dcl/inspector.svg)](https://www.npmjs.com/package/@dcl/inspector) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) \[CI状态\] (

## 安装

```sh
npm install @dcl/inspector
```

也可以使用：`pnpm add @dcl/inspector`、`yarn add @dcl/inspector`、`bun add @dcl/inspector`

## README

# @ dcl/ 检查器

[![npm version](https://img.shields.io/npm/v/@dcl/inspector.svg)](https://www.npmjs.com/package/@dcl/inspector) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![CI Status](https://github.com/decentraland/creator-hub/workflows/Inspector/badge.svg)](https://github.com/decentraland/creator-hub/actions/workflows/inspector.yml)

Decentrand的基于反应的场景编辑器接口,为场景编辑和操纵提供了模块化的架构.

## 目录

-   [特征](https://npmcn.com/package/%40dcl/inspector/#readme-features)
-   [快速启动](https://npmcn.com/package/%40dcl/inspector/#readme-quick-start)
-   [有资产包的地方发展](https://npmcn.com/package/%40dcl/inspector/#readme-local-development-with-asset-packs)
-   [一体化](https://npmcn.com/package/%40dcl/inspector/#readme-integration)
    -   [WebSocket 集成系统](https://npmcn.com/package/%40dcl/inspector/#readme-websocket-integration)
    -   [IFrame 整合](https://npmcn.com/package/%40dcl/inspector/#readme-iframe-integration)
-   [配置](https://npmcn.com/package/%40dcl/inspector/#readme-configuration)
-   [测试](https://npmcn.com/package/%40dcl/inspector/#readme-testing)
-   [解决问题](https://npmcn.com/package/%40dcl/inspector/#readme-troubleshooting)
    -   [共同问题](https://npmcn.com/package/%40dcl/inspector/#readme-common-issues)
-   [开发提示](https://npmcn.com/package/%40dcl/inspector/#readme-development-tips)
-   [依赖关系](https://npmcn.com/package/%40dcl/inspector/#readme-dependencies)
-   [相关的结构决定](https://npmcn.com/package/%40dcl/inspector/#readme-related-architecture-decisions)
-   [许可证](https://npmcn.com/package/%40dcl/inspector/#readme-license)

## 特征

-   **实体等级**: 基于树的场景管理,包含组件操作
-   **构成部分检查员**: 所有组件类型的专业编辑
-   **级别编辑器**: 三维场景可视化与巴比伦.js
-   **资产管理**当地资产、定制物品和资产包支助(通过 `@dcl/asset-packs`(中文(简体) )

## 快速启动

### 先决条件

-   **节点.js** 22.x或更高
-   **分散式SDK7场景** (或创建一个与 `npx @dcl/sdk-commands init`(中文(简体) )
-   **基本谅解** 或 IFrame 通讯

### 开始

1.  启动 CLI 服务器 :

```bash
npx @dcl/sdk-commands start --data-layer --port 8001
```

2.  向检查员提供服务(选择一种方法):

```bash
# Method 1: Development server (from monorepo)
git clone https://github.com/decentraland/creator-hub.git
cd creator-hub
make init
cd packages/inspector
npm start

# Method 2: From node_modules
npm install @dcl/inspector
npx http-server node_modules/@dcl/inspector/public
```

3.  访问检查员:

```
http://localhost:8000/?dataLayerRpcWsUrl=ws://127.0.0.1:8001/data-layer
```

何处 `http://localhost:8000` 是检查者的URL,并且 `ws://127.0.0.1:8001/data-layer` 是 CLI 服务器的 WebSocket URL .

## 有资产包的地方发展

使检查专员与当地资产组合相结合:

1.  **启动资产组合dev环境:**
    
    ```bash
    cd packages/asset-packs
    npm run start  # Starts SDK7 server on port 8001
    ```
    
2.  **在另一个终端中, 启动嵌入器内容服务器 :**
    
    ```bash
    cd packages/asset-packs
    docker-compose up  # Starts content server on port 9000
    ```
    
3.  **在另一个终端, 上传资产到本地内容服务器 :**
    
    ```bash
    cd packages/asset-packs
    npm run upload  # Uploads to http://localhost:9000
    ```
    
4.  **启动检查器 Dev 服务器 :**
    
    ```bash
    cd packages/inspector
    npm start  # Starts on port 8000
    ```
    
5.  **配置检查员以使用本地资产包 :**
    
    利用这些参数访问检查专员:
    
    ```
    http://localhost:8000/?contentUrl=http://localhost:9000/asset-packs&binIndexJsUrl=http://localhost:8001/bin/index.js
    ```
    
    -   `contentUrl`: 对本地内容服务器进行资产加载的指针
    -   `binIndexJsUrl`: 为智能项目运行时间访问本地 SDK7 dev 服务器

见 [主读取器](https://npmcn.com/package/README.md) 为完整的本地开发设置指令.

### 在当地测试新资产

检查员在运行时间从S3取出资产目录. 若为 `latest/catalog.json` 无法获取(例如,在预置的PR分支上,在CI中,或离线),它自动倒回 `catalog.json` 捆绑在 `@dcl/asset-packs` npm包-所以督察总是会装入.

当你添加一个 **新设** 本地资产不会自动出现在“资产包”标签中,因为CDN和捆绑的目录尚不清楚。 有两种选择:

#### 备选方案1——多克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克

跟随资产包装 [地方发展](https://npmcn.com/package/%40dcl/asset-packs/README.md#local-development) 设置( docker- 构成 +) `npm run upload`) (中文(简体) ). 上传脚本也发布 `catalog.json` 作为 `asset-packs/latest/catalog.json` 给MinIO,像CI一样 然后打开检查员:

```
http://localhost:8000/?contentUrl=http://localhost:9000/asset-packs
```

目录和所有资产文件都在当地提供——不需要远程CDN.

#### 备选案文2——通过PR上传到dev CDN

推出你的分行并评论 `/upload-assets` (仅限成员参加)。 CI 将所有资产文件上传到开发 CDN(`https://builder-items.decentraland.zone`并张贴确认意见.

要测试dev CDN:

```
http://localhost:8000/?contentUrl=https://builder-items.decentraland.zone
```

这给出了一个包含真实资产文件的完整端到端测试. 请注意: `latest/catalog.json` dev CDN 上仅在合并时更新到 `main`,因此在合并前使用 Docker 选项查看目录更改.

## 一体化

检查专员支持两种一体化办法:

### WebSocket 集成系统

利用国家综合倡议开发环境:

```typescript
// Connect to CLI's WebSocket server
const inspectorUrl = `http://localhost:3000/?dataLayerRpcWsUrl=ws://127.0.0.1:8001/data-layer`
```

### IFrame 整合

对于嵌入网络应用程序,检查员:

```typescript
function initRpc(iframe: HTMLIFrameElement) {
  const transport = new MessageTransport(window, iframe.contentWindow!)
  const storage = new StorageRPC(transport)

  // Handle file operations
  storage.handle('read_file', async ({ path }) => {
    return fs.readFile(path)
  })

  storage.handle('write_file', async ({ path, content }) => {
    await fs.writeFile(path, content)
  })

  // ... other handlers

  return {
    storage,
    dispose: () => storage.dispose()
  }
}

function InspectorComponent() {
  const iframeRef = useRef()

  const handleIframeRef = useCallback((iframe) => {
    if (iframe) {
      iframeRef.current = initRpc(iframe)
    }
  }, [])

  useEffect(() => {
    return () => iframeRef.current?.dispose()
  }, [])

  const params = new URLSearchParams({
    dataLayerRpcParentUrl: window.location.origin
  })
  const inspectorUrl = `http://localhost:3000/`
  const url = `${inspectorUrl}?${params}`

  return <iframe onLoad={handleIframeRef} src={url} />
}
```

## 配置

通过 URL 参数或全局对象配置检查器 。 所有配置选项都可以使用任一方法设置 :

```typescript
type InspectorConfig = {
  // Data Layer Configuration
  dataLayerRpcWsUrl: string | null // ?dataLayerRpcWsUrl=ws://...
  dataLayerRpcParentUrl: string | null // ?dataLayerRpcParentUrl=https://...

  // Smart Items Configuration
  binIndexJsUrl: string | null // ?binIndexJsUrl=https://...
  disableSmartItems: boolean // ?disableSmartItems=true

  // Content Configuration
  contentUrl: string // ?contentUrl=https://...

  // Analytics Configuration
  segmentKey: string | null // ?segmentKey=...
  segmentAppId: string | null // ?segmentAppId=...
  segmentUserId: string | null // ?segmentUserId=...
  projectId: string | null // ?projectId=...
}

// Method 1: Global configuration
globalThis.InspectorConfig = {
  dataLayerRpcWsUrl: 'ws://127.0.0.1:8001/data-layer',
  contentUrl: 'https://builder-items.decentraland.org'
}

// Method 2: URL parameters
// http://localhost:3000/?dataLayerRpcWsUrl=ws://127.0.0.1:8001/data-layer&contentUrl=https://builder-items.decentraland.org&disableSmartItems=true
```

配置选项按以下顺序解决:

1.  URL 参数( 最高优先级)
2.  全球目标
3.  默认值( 最低优先级)

## 测试

运行所有检查员测试 :

```bash
make test-inspector
```

以监视模式运行特定测试文件 :

```bash
make test-inspector FILES="--watch packages/@dcl/inspector/src/path/to/some-test.spec.ts"
```

## 解决问题

### 共同问题

1.  **WebSocket 连接**
    
    -   校验 CLI 服务器运行中 `--data-layer` 旗帜
    -   检查 WebSocket URL 匹配 CLI 服务器端口
    -   确保没有防火墙屏蔽连接
2.  **文件系统访问**
    
    -   检查文件权限
    -   验证 CLI 有必要的访问权
    -   确保路径格式正确
3.  **资产加载**
    
    -   校验 `contentUrl` 正在正确配置
    -   检查内容服务器的网络访问权限
    -   确保资产路径有效

## 开发提示

1.  **调试**
    
    -   使用 Chrome DevTools 检查 WebSocket
    -   启用复用 DevTools
    -   RPC 信件监视浏览器控制台
2.  **测试**
    
    -   单位测试中使用模拟执行
    -   Mock RPC呼吁整合测试
    -   测试WebSocket和IFrame运输

## 依赖关系

检查员是 [创建中心单列波](https://npmcn.com/package/) 取决于:

-   **`@dcl/asset-packs`** - 资产包和智能项目运行时间(地点: `packages/asset-packs`(中文(简体) )

关于资产组合一体化的地方发展,见 [主读取器](https://npmcn.com/package/README.md) 用于设置指令.

## 相关的结构决定

为了更深入地了解结构和设计决定:

-   [ADR- 281: 分散工具的项目](https://adr.decentraland.org/adr/ADR-281) - 解释项目抽象和检查专员如何使用
-   [ADR-282:权力下放检查员](https://adr.decentraland.org/adr/ADR-282) - 详细说明检查专员的结构、一体化办法和技术决定

## 许可证

Apache 2.0 (英语)

## 常见问题

### @dcl/inspector 是什么？

\[CI状态\] \(

### 如何安装 @dcl/inspector？

在项目目录运行 npm install @dcl/inspector，或使用 pnpm add / yarn add / bun add。

### @dcl/inspector 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dcl/inspector 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dcl/inspector 可以商用吗？

@dcl/inspector 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @dcl/inspector 的下载量有多少？

根据 npm 官方下载统计，@dcl/inspector 在 2026/10/12 – 2026/11/10 这 30 天内被下载 17,331 次，日均约 578 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dcl/inspector 还在维护吗？

最新版本 7\.61\.2 发布于 2026/11/10（2 天前）；至今共发布 1033 个版本，其中过去 12 个月发布了 168 个；首次发布于 2023/02/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。