Editor 常见问题
按启动、依赖、文档冲突、预览、插件和打包问题定位原因并保留可复查证据。
源码启动失败
从仓库根目录执行 pnpm install --frozen-lockfile 和 pnpm dev:editor。前者安装依赖，后者先构建编辑器、模板与 SDK。直接打开某个旧 dist 不能证明当前源码构建成功。
核对 Node.js 22.12+、pnpm 12.3.4。macOS 编译嵌入层失败时检查 Xcode Command Line Tools 与错误里要求的 Electron Node-API 头文件；只有运行 Native 游戏时还需 Rust/Cargo 及系统链接器。
依赖安装或下载卡住
查看安装日志中的工具、URL、状态码与首个错误，检查系统代理/PAC、网络与磁盘空间。编辑器受管工具位于用户数据目录，不要求覆盖全局 Node 或 Rust。取消后可重试，但不要删除项目或写作数据目录来处理网络问题。
文件无法保存
先看是否有磁盘冲突、文件被删除、项目路径变化或权限错误。保留未保存文本，先比较差异，再选择载入磁盘或保存本地；不要用外部覆盖跳过版本校验。编辑器尚无通用崩溃草稿恢复和自动三方合并，重要改动及时保存并纳入版本控制。
预览不能启动或定位不符
| 现象 | 检查 |
|---|---|
| 无法运行 | 当前目录的项目配置、dev:web/dev 或 dev:native 脚本、依赖安装与首个运行错误 |
| Native 不支持 | 当前仅 macOS 图层内嵌；Windows/Linux 不提供图像传输回退 |
| 到光标不可用 | .qs 编译错误、当前源码位置、是否接入 editor-core/runtime 与注册脚本工厂 |
| 变量/前章状态不同 | 定位只重放目标文件及开发基线，不推断先前章节的选择 |
| 保存后跳回开头 | 当前步骤删除/不再能可靠匹配，或文件尚未定位；这是恢复范围的限制 |
| 音乐没响 | 预览静音、游戏音量、浏览器用户激活、资源加载与 AudioContext 状态 |
| 存档停止后消失 | 检查是否使用临时 Web 分区或 Native Demo 内存后端 |
角色或动画面板没更新
角色识别依赖已保存的静态项目索引，动态注册或复杂运行时工厂可能无法解析。角色/资源 ID 重命名不会重写故事引用。
动画先「应用到源文件」，再保存。没有静态 @PlayAnimation 调用时手动选场景；运行时选择需玩家实际处理。保持未应用草稿，按面板提示处理源码版本冲突。
插件、写作与打包
插件先检查实际安装依赖、启用状态、Registry 原因与运行入口；“安装成功”不证明 runtime 接线完成。写作检查提供商设置、额度与阶段状态，模型生成结果仍需人工阅读，导出草稿也不表示已经审核。
生产打包看首个失败步骤与日志；关闭面板不会取消，跳过公证不代表公证通过。完成后检查实际生产产物，详见生产打包。
报告问题
记录当前源码/Editor 版本、操作系统与架构、Web/Native 目标、复现步骤、首个错误和最小项目。附带相关日志、项目配置与截图时移除凭据、私有路径和正文中的敏感信息。说明证据来自开发预览、生产目录还是独立应用，便于复查。