> 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 进行氛围编程](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md) 有关设置和提示 AI 助手的更多详情。

你也可以让 AI 调试场景 *在其运行时*。Decentraland 桌面客户端可以暴露一个 MCP 服务器，让代理自己截屏、读取场景的控制台输出、带玩家在场景中走动，并点击对象——因此，代理可以自己复现问题、观察发生了什么，并反复迭代直到修复。使用 `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`。一旦两者都 `complete`，请让受影响的玩家完全退出并重新启动 Decentraland。

#### 问题：发布一直卡在“Converting”阶段，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`。如果加上这个标志后模型看起来正常，那么问题一定与模型转换中的 bug 有关。在这种情况下， [报告问题](/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)中检查你的预算，然后重新发布。参见 [Worlds 大小限制](/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.