> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/troubleshooting.md).

# 故障排除

常见问题的修复方法

## 使用 AI 助手进行调试

在深入查看下面这些问题之前，不妨把问题交给 AI 助手，比如 Cursor 的聊天、GitHub Copilot 或 Claude Code。把控制台里的错误信息贴给它，或者描述一下哪里没有按预期运行，它通常就能在你场景的代码中找到问题并帮你修复。

为了取得良好效果，请确保 AI 已安装 Decentraland SDK 技能。这些技能会教它 SDK 的模式和限制，这样它就不会根据通用或过时的信息瞎猜。请在你的场景项目中运行以下命令来安装：

```bash
npx skills add decentraland/sdk-skills
```

参见 [使用 AI 进行 Vibe Coding](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md) 了解更多关于设置和提示 AI 助手的细节。

你也可以让 AI 调试场景 *在运行时*。Decentraland 桌面客户端可以公开一个 MCP 服务器，让代理自己截屏、读取场景的控制台输出、在场景中移动玩家，以及点击对象——因此，与你手动复现 bug 并贴出错误不同，代理可以自己复现，查看发生了什么，并不断迭代直到修复为止。使用 `npm run start -- --mcp` 启动场景，并将你的代理连接到它。

参见 [让 AI 在世界中看到你的场景](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md#let-the-ai-see-your-scene-in-world) 了解完整设置，并安装 `unity-explorer-mcp` 技能，这样代理就能了解工作流程：

```bash
npx skills add decentraland/sdk-skills --skill unity-explorer-mcp
```

## 运行预览时的问题

#### 问题：无法运行任何场景预览，错误信息提到 **权限被拒绝** 或 **EACCES**

你的操作系统不允许你更改要运行项目的文件夹权限。运行场景时，需要安装一些依赖，但这被禁止了。你需要配置该文件夹的权限，以允许你的 Windows/Mac/Linux 用户账户在其中编辑文件。

有用资源：

* [docs.npmjs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
* [letscodepare](https://letscodepare.com/blog/npm-resolving-eacces-permissions-denied)

#### 问题：无法运行某个特定场景的预览，错误显示 **错误：构建项目时出错**

如果你运行的是别人分享给你的场景，请确保这个场景不是在包含一个 `node_modules` 或 `bin` 文件夹或一个 `package-lock.json` 文件的情况下分享的。这些文件包含使用特定于你的操作系统和机器版本的依赖项，它们应该在首次运行场景时生成。请手动删除这些文件夹和文件，然后再运行 `npm run start` 。

#### 问题：运行 `npm run start` 能运行，没有错误信息，但浏览器窗口没有打开，输出中也没有可用于打开预览的 URL

请确保你的 Node 版本是最新的。必须是 20 或更高版本。

#### 问题：运行 `npm run start` 会打开浏览器标签页，但加载界面一直无法完成加载，或者我看到一个红色错误横幅，上面写着“critical error”。

* 请确保你的项目中安装了最新版本的 Decentraland SDK。运行：

  `npm i @dcl/sdk@latest`

#### 问题：场景运行时，我在控制台里看到 `循环依赖` 警告。

这指的是你场景中的文件相互引用。这不一定是问题，但这不是编写软件时推荐的模式，因为它可能导致难以调试的竞争条件和其他问题。尽管有这些警告，你的场景很可能仍然运行良好。

理想情况下，你场景中的代码加载应遵循清晰的顺序。带有循环依赖的代码可能会遇到“先有鸡还是先有蛋”的问题，即编译器不知道该先初始化哪一个。通常这可以无问题地解决，但最好避免。

要修复这些依赖关系，通常需要改为调用函数或对象构造器，并在函数参数中传入已经实例化的实体/对象引用；而不是在函数中硬编码对这些实体/对象的引用，因为它们可能已经实例化，也可能还没有。

## 部署时的问题

#### 问题：你没有权限部署到这些地块

* 请确保 `scene.json` 文件正确列出了你要部署的坐标。
* 请确保 Metamask 已正确设置，以使用正确的钱包签署交易。这个钱包可以是拥有 LAND 代币的钱包，或者是由所有者授予了操作员权限的钱包。

#### 问题：运行 `npm run deploy` 失败

* 检查你场景的出生点，出生点的三个 x、y、z 坐标都必须是数字或范围。要么三者全是数字，要么三者全是范围。不支持有些是范围而有些是数字。

  例如，这种写法不受支持：

  `"position": {"x": [1,4], "y": 0, "z": [1,4]}`

  这种写法受支持：

  `"position": {"x": [1,4], "y": [0,0], "z": [1,4]}`
* 你被分配到的默认 catalyst 服务器可能已宕机或出现问题。你可以强制 `npm run deploy` 命令改为部署到特定的 catalyst 服务器。要在 Decentraland Editor 中部署到指定服务器：

  1. 打开你的场景并点击 **发布**
  2. 选择 **发布到不同服务器** 底部的选项。
  3. 在下拉菜单中，选择 **自定义服务器**
  4. 输入服务器地址，例如 `peer-ec1.decentraland.org`
  5. 点击 **发布到自定义服务器**
  6. 像正常部署一样批准该交易。

  通过 CLI 执行此操作：

  `npm run deploy -- --target-content <server-name>`

  例如：

  `npm run deploy -- --target-content peer-ec1.decentraland.org`

  参见 [catalyst-monitor](https://decentraland.github.io/catalyst-monitor/) 查看 catalyst 网络中所有服务器的状态。你也可以从每张卡片顶部复制各自的地址。
* 检查你场景的 `package.json`。一个常见问题是存在一个 `bundleDependencies` 以及一个 `bundledDependencies` （多了一个 d）部分。这有时是由于在同一项目上不同时期使用了不同的 Node 版本，或者项目在多个使用不同 Node 版本的人之间共享所导致的。删除 `bundleDependencies`，它与较旧的 Node 版本有关。

同时确保你的 Node 版本是最新的，至少是 20 版本。

#### 问题：运行 `npm run deploy` 或 `npm run build` 报告类型错误

你的场景可能会被 TypeScript 报告类型错误，例如提示某个变量的类型可能是 `任何` 或者 `undefined` 或 `null` 是不允许的。在运行 `npm run deploy`时，它也会运行 `npm run build`，它在这些检查上比 `npm run start`.

不同于 JavaScript，TypeScript 会对所有变量实施严格类型检查。即使你的场景编写方式保证例如某个值永远不会是 `undefined`，TypeScript 也需要知道在那种情况下会发生什么，或者你需要显式说明该值只能是例如字符串。

作为替代方案，你可以运行 `npm run deploy -- --skip-build` 以跳过运行 `npm run build`，并阻止这些检查运行。

#### 问题：我已部署场景，但进入 Decentraland 时看不到更改

* 请记住，如果场景包含较大的资源，这可能需要几分钟。
* 在新版本的 3D 模型被转换为资源包期间，玩家会刻意看到你场景上一个完全可用的版本。通常这只需要几秒钟，但对于非常大的场景或服务器繁忙时可能会更久。你可以 [直接查看转换状态](/creator/content-creator-zh/chang-jing-bian-ji-qi/fa-bu/publish-scene.md#check-the-conversion-status) 。
* 仅仅重新加载场景不足以获取新版本：重新加载会重启场景代码，但不会拉取新发布的版本。一旦转换完成，请完全退出并重新启动 Decentraland，然后通过跳转链接或 `/goto` 聊天命令再次进入场景。

#### 问题：有些玩家看到我场景的新版本，其他人仍然看到旧版本

你场景的 3D 模型转换在不同平台（Windows 和 Mac）上完成的时间不同，而且每个玩家的客户端也会保留本地缓存。要检查所有平台的转换是否完成， [直接查看转换状态](/creator/content-creator-zh/chang-jing-bian-ji-qi/fa-bu/publish-scene.md#check-the-conversion-status) 并比较 `windows` 和 `mac` 在 `assetBundles`下的值。等两者都 `完成`后，请让受影响的玩家完全退出并重新启动 Decentraland。

#### 问题：发布卡在转换阶段，Jump In 按钮始终不出现

你的场景要么排在其他正在转换的场景后面等待，要么转换失败了。

* 打开 `https://asset-bundle-registry.decentraland.org/queues/status` 并查找你场景的实体 ID。你可以在 `entityId` 字段中找到该 ID，当你 [直接查看转换状态](/creator/content-creator-zh/chang-jing-bian-ji-qi/fa-bu/publish-scene.md#check-the-conversion-status) 使用你场景的坐标时。如果你的 ID 在队列中列出，说明场景正在排队，你只需要等待。
* 如果不在队列中， [直接查看转换状态](/creator/content-creator-zh/chang-jing-bian-ji-qi/fa-bu/publish-scene.md#check-the-conversion-status) 的场景。如果某个平台显示 `失败`，请再次发布场景。如果第二次仍然失败， [报告问题](/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/report-bug.md) 并附上实体 ID。

#### 问题：部署后，某些 3D 模型缺失、发黑或没有贴图

* 如果你刚刚发布，模型转换为资源包可能还没完成。请输入 `/detectabs` 到聊天窗口：被染成红色的模型尚未转换。 [检查转换状态](/creator/content-creator-zh/chang-jing-bian-ji-qi/fa-bu/publish-scene.md#check-the-conversion-status) 并等待其完成。
* 确保所有 3D 模型都在场景边界内，包括它们的包围盒。如果模型的任何部分在运行预览时超出了这些限制，这些超出的部分将被裁剪并不会渲染，在预览和已发布的场景中都是如此。
* 如果问题是贴图，请记住，在转换过程中，3D 模型中的贴图尺寸上限为 1024x1024 像素。

#### 问题：场景近看没问题，但从远处看却损坏或缺失

用于从远处渲染场景的低细节层级（LOD）资源版本，会在发布的最后阶段生成，可能还没有完成。这不会阻止你从近处测试场景。 [检查转换状态](/creator/content-creator-zh/chang-jing-bian-ji-qi/fa-bu/publish-scene.md#check-the-conversion-status) 并查看 `lods`下的值，或者 պարզապես 等待后稍后再检查。

#### 问题：部署后，我的 3D 模型看起来不同了

* 如果贴图看起来不同，请记住，3D 模型中的贴图尺寸上限为 1024x1024 像素。执行这种转换是为了确保 Decentraland 对所有人都能流畅运行。
* 如果模型看起来不同，可能是模型转换为资源包时出了问题。了解更多关于资源包压缩的信息 [这里](/creator/content-creator-zh/chang-jing-sdk7/you-hua/performance-optimization.md#asset-bundle-conversion).

  要验证这一点，尝试使用 URL 参数运行场景 `&DISABLE_ASSET_BUNDLES`。如果启用这个标志后模型看起来正常，那么问题一定与模型转换中的错误有关。在这种情况下， [报告问题](/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/report-bug.md) 并附上你部署的实体 ID。

  请注意，将模型生成压缩资源包版本需要服务器一些时间（通常几分钟，场景非常大或服务器繁忙时更久）。你可以通过在聊天窗口中输入以下命令来检查模型是否正在作为压缩资源包加载 `/detectabs`。压缩模型会被染成绿色，未压缩的会被染成红色。

  你也可以在发布前通过启用本地复现这种转换， [预览中的优化资源](/creator/content-creator-zh/chang-jing-sdk7/ru-men/preview-scene.md#preview-with-optimized-assets)。这可以让你在无需部署场景的情况下捕获并调试这些问题。

#### 问题：我的场景完全消失了

* 如果场景在 World 中：你的 Worlds 存储配额可能已超出，例如在出售或转移 NAME、LAND 或 MANA 之后。你有 48 小时来释放空间或增加配额，否则你的 Worlds 将无法访问。请在 Creator Hub 的 **管理** 选项卡中或在 **Worlds** 选项卡中查看你已使用和剩余的存储额度。 [Builder](https://decentraland.org/builder/worlds)中查看你的配额，然后重新发布。参见 [World 大小限制](/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/kinds-of-project.md#size-limits).
* 如果场景在 LAND 上：具有部署权限的人可能已在你的地块上发布了一个新场景，从而抹去了先前内容。参见 [场景覆盖](/creator/content-creator-zh/chang-jing-sdk7/fa-bu/publishing.md#scene-overwriting).
* 在极少数情况下，违反 Decentraland 内容政策的内容可能会被内容服务器列入拒绝名单。如果你认为这是误判，请通过 [Decentraland Discord](https://decentraland.org/discord).

#### 问题：我的场景在生产环境中的 FPS 很低，尽管在预览中运行很流畅。

你的场景性能可能会受到邻近场景的不良实践影响，因为它们也在并行运行。你可以通过打开设置并将视野距离设置为最小来验证是否如此，这样只会加载当前场景周围 1 个地块。

你还可以通过使用参数运行场景来进一步减小视野距离 `&LOS=0`，以完全不加载任何周围场景。

如果你刚刚部署了场景，在场景加载时的负担也可能会在服务器将场景中的 3D 模型转换为压缩资源包后减轻。你可以通过在聊天窗口中输入以下命令来检查模型是否正在作为压缩资源包加载 `/detectabs`。压缩模型会被染成绿色，未压缩的会被染成红色。

### 报告错误

如果你遇到的问题不是你的场景本身的问题，而是 Decentraland SDK 的一般问题，请参阅 [报告错误](/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/report-bug.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.