# 性能
## 你会学到什么
- 为什么示例强烈建议使用 release 构建。
- 哪些因素会拉长导出耗时。
- 如何使用 `gpu` 特性请求上游 GPU 路径。
- 如何为长曲、FLAC 和生成式作品安排验证流程。
## 适合谁读
当 `kawaii_bass_3min`、管弦示例、颗粒合成或 FLAC 导出很慢时读本章。
## 前置知识
- [WAV、FLAC、MIDI](wav-flac-midi.md)
- [Cargo 特性](../05-rust-integration/features.md)
## 心智模型
`mlua-pulse` 的导出是离线渲染。耗时主要来自合成、效果、采样处理、响度扫描、编码和文件写入。debug 构建保留调试信息和较少优化，release 构建会大幅降低示例运行时间。
播放不是性能基准。最终交付应以离线导出和自动测试为准。
## 最小可运行例子
```powershell
cargo run --release --example foundation_loop
cargo run --release --example kawaii_bass_3min
cargo run --release --example moonlight_golden_hall
```
请求 GPU 特性：
```powershell
cargo run --release --features gpu --example foundation_loop
```
Lua 侧：
```lua
song:export_wav("output/gpu.wav", { gpu = true })
```
## 参数和边界
长曲耗时与时长、轨道数、效果数量、采样率、标准化方式和编码格式相关。RMS 标准化需要统计整体能量，FLAC 编码需要额外压缩，颗粒合成和复杂效果会增加计算。
`gpu = true` 只有在 crate 启用 `gpu` 特性时有效。未启用却请求 GPU 会返回 `gpu feature is not enabled`。GPU 是加速请求，不改变音乐语义，也不保证所有机器都更快。
## 常见陷阱
不要用 debug 构建评价示例耗时。用户已经观察到 release 可以大幅降低运行时间，因此文档和示例命令都应优先使用 `--release`。
不要为了快而跳过最终导出验证。尤其是响度、FLAC、PCM 和 MIDI 路径，必须用测试和实际导出命令确认。
不要用 `cargo check --all-features`。`mlua` 特性组合需要分别验证。
## 进阶用法
开发阶段可以只导出 WAV 草稿，等编曲和混音稳定后再导出 FLAC 和 MIDI。长曲可以先缩短 section repeat 数量测试结构，再恢复完整长度。
如果要批量渲染，建议宿主层组织队列，每首歌使用 release 二进制运行，并把输出放进独立目录。Lua 脚本内保持音量和标准化选项一致，避免后期手动拉平响度。
## 相关章节
- [故障排查](troubleshooting.md)
- [响度标准化](loudness.md)
- [Cargo 特性](../05-rust-integration/features.md)
- [示例索引](../06-reference/examples.md)