常见问题与排查

从资源、插件、平台和依赖四个方向定位问题。

预览空白或停在载入中

先查看终端和浏览器控制台，确认启动异常没有被 UI 隐藏。检查初始场景是否执行、资源根目录是否存在、renderer 是否接到了引擎投影。开发期正常而生产失效时，检查构建资源索引和 CSP，而不是继续修改剧本文本。

确认功能包提供 ./script-compiler 入口且已被当前编译配置激活。检查拼写、参数与空行附着。运行时 .use(new Plugin()) 并不自动证明编译器已经发现其装饰器。

检查目标类型和注册。-> nodeName 请求一个节点，不会生成该节点。没有目标的选项本来就会选择后继续。对动态节点还要检查包是否已激活、入口是否保留来源。

先手动点击页面，检查 AudioContext 是否解锁，再检查资源编码、包路径、总线增益和音频意图。Cocos/Native 则检查宿主能力与音频后端，不套用浏览器解锁规则。

逻辑舞台采用固定比例等比缩放，留边可能是预期行为。不要用裁剪或更改逻辑宽度解决它。需要竖屏构图时选择 portrait 预设并重新安排安全区域。

检查 target manifest 中的 javascriptcore 标识、jscVersion、签名宿主和模块元数据是否匹配。清理并重新生成受影响的构建产物；不要恢复已移除的 QuickJS 路径。

保留完整报错和具体包版本，核查注册表来源与已有锁文件。不要直接关闭安全策略。文档站有独立的锁文件和依赖工程，不需要为了预览文档重装完整引擎依赖。

附上操作系统、Node/pnpm 版本、目标平台、所用 commit、最小剧本或资源结构、复现步骤和实际错误。不要上传 API 密钥、私有故事内容或不允许分发的素材。