排障
遇到问题时，最快的路径是先导出诊断包，再提 Issue。诊断包里已经有定位需要的大部分信息，不需要你手工翻日志。
导出诊断包
在 设置 › 关于 › 诊断包 点「导出诊断包」，选保存位置，得到一个 zip：
env.json：应用版本、Electron / Chrome / Node 版本、操作系统、数据目录、当前页面与工程。settings.json：当前的设置对象。logs/：最近 7 天的错误日志与操作轨迹。chart/project.json：只有勾选「附带当前谱面（不含音频和封面）」时才有。
诊断包不含登录凭据，也不会附带音频与封面。日志按 UTC 天切分、单文件 5MB 封顶、保留 7 天，所以不用担心里面堆着很久以前的东西。
在线版的 设置 › 关于 里没有这一项（依赖桌面端）；反馈在线版问题时，写明浏览器版本与复现步骤即可。
把 zip 附在 GitHub Issues 的问题描述里，再写清版本、平台与复现步骤。
应用崩溃或某一页打不开
应用把错误拦在三层，各给一个弹窗：
| 弹窗 | 范围 | 能做什么 |
|---|---|---|
| 应用遇到问题 | 整个应用 | 「重试」重建界面；不行就导出诊断包 |
| 这一页无法显示 | 单个页面 | 重试这一页；其它页面仍可切换 |
| 画布无法显示 | 工作台画布 | 重试画布；工作台其它部分仍可用 |
崩溃时操作轨迹会先落盘再打包，所以崩溃当下导出的诊断包最有价值。
常见故障
音频导入失败
提示「音频解码失败」或「该文件无法解码为音频」时，换一个文件重试；尽量用常见格式（MP3、OGG、WAV）。
提示音频文件丢失或与工程记录不一致
- 丢失：工程记录的音频文件不在磁盘上了。可以在音频页重新导入，或「清除音频记录」——注意清掉后曲目归属会转为「自定义曲目」。
- 不一致：磁盘上的音频与工程记录不是同一份（时长对不上）。按提示「按音频重新对齐」会更新谱面时长，同样把归属转为自定义。
仿真场 / 视频导出提示素材缺失
仿真场需要本地的场地与背景素材。先回预览页让素材加载一次，再重新导出；仍然失败说明素材不完整，带上诊断包反馈。
视频导出提示这台电脑导不出
视频导出依赖 WebCodecs。换最新版 Chrome / Edge，或改用桌面版重试。
数据目录打不开 / 搬家失败
- 目标位置必须是空文件夹；已有内容时会被当成父目录，实际落到其下的同名文件夹。
- 不能把数据目录改到当前位置的内部或父目录。
- 权限不足（例如系统保护目录）会失败，换一个可写的位置。
- 搬家失败会保留原来的保存位置，不会两头都没有。
更新检查失败
提示「暂时查不到更新」通常是网络问题。更新源是 GitHub Releases：稍后重试，或直接从 Releases 下载新版本安装包。国内网络下载慢的话，用 CNB Releases 下载安装包。
改动没有保存下来
谱面工程的自动保存失败时不会弹窗，只在日志里留一行。发现改动丢失时：
- 不要继续大改，先导出诊断包（里面有失败时的日志）。
- 确认数据目录所在磁盘没有满、目录可写（设置 › 存储与数据 可打开该目录）。
- 带上诊断包与复现步骤提 Issue。
提 Issue 时写什么
text
版本：设置 › 关于 里显示的版本号
平台：Windows 11 / macOS 15 / Ubuntu 24.04 …
现象：发生了什么，期望是什么
复现：1. … 2. … 3. …
诊断包：已附（导出时间 …）AAO Editor 没有远程遥测——除你主动提交的内容外，维护者拿不到你的任何运行信息。