unity-build-size

Unity 构建体积

让 Unity 玩家构建产物低于体积限制：测量受限的对象，修复占用最多的少数资源和设置，重新构建，并验证结果可以运行。目标版本为 Unity 6.3 LTS (6000.3)；这些脚本已在 glTFast 6.20.0 项目中测试。现有项目请沿用 ProjectSettings/ProjectVersion.txt 中的版本。

以下脚本路径均相对于此技能文件夹。两个脚本均为只读的标准库 Python 3.10+ 脚本。

1. 确定受限对象

构建产物有多种体积，优化错了对象会浪费用户的时间。先确定受限的是哪个文件以及限制是多少，然后只阅读对应的参考资料：

目标	通常受限的对象	阅读
浏览器（itch.io、各类门户、自有网站）	Build/ 中的每个文件（itch.io：每个文件 200 MB）和压缩后的下载包	references/platform-web.md
Android（APK、AAB、Google Play）	Play 根据 AAB 计算出的下载体积	references/platform-android.md
iOS（App Store、TestFlight）	每台设备对应的精简下载包	references/platform-ios.md
Windows、macOS、Linux（zip、jam、Steam）	压缩包、安装文件夹或 Steam 补丁体积	references/platform-desktop-steam.md

如果用户只给出了数值，却没说明对应哪个文件，请只问这一个问题。若没有硬性限制，就选择用户实际付费的对象（下载包、安装体积、补丁体积），并说明测量的是哪一种。修改任何内容之前，先记下该文件当前的体积，作为对比基准。

2. 测量发布内容

构建一次（或使用本次 Editor 会话中最近一次构建），并总结 Build Report：

python scripts/build_report.py ~/Library/Logs/Unity/Editor.log --top 20

日志路径：Windows %LOCALAPPDATA%\Unity\Editor\Editor.log，Linux ~/.config/unity3d/Editor.log，批处理模式下为 -logFile 路径。类别说明了哪类数据占主导；资源列表则说明了哪些文件占用空间。体积为未压缩的 MiB，因此不是下载体积：务必与第 1 步测量的文件进行比较。

如果已安装 Unity CLI（unity --version），可用它构建并保存日志： unity build . --profile "<Build Profile name>" --output-path <output path> --log-file build.log，然后运行 build_report.py build.log。否则，请使用 Editor 的 Build Profiles 窗口或项目的构建脚本。

3. 找出项目中的原因

# --platform: the one you ship, as Standalone, Android, iPhone or WebGL
python scripts/check_unity_build_size.py path/to/Project --platform WebGL --max-texture-size 2048

如果未设置正确的 --platform，就不会检查对应平台的纹理覆盖设置。每条 WARNING 都会列出一个文件、相关设置、预估构建成本以及一行 fix:；NOTE 则提供背景信息。检查器无法判断构建会引用哪些资源，因此需要结合 Build Report 查看：未被任何已发布场景使用的资源不会产生任何成本。

4. 先处理占比最大的类别

先做最小改动，每次处理一个类别，这样下一次测量就能看出每项修复带来了什么变化。

• 包含嵌入图像的 glTF/GLB（gltf-embedded-texture）：glTFast 会以未压缩形式打包这些图像，而且没有可用于修复的 Texture Importer。运行检查器的 fix: 命令，或将图像移出；首次处理前请阅读 references/gltf-textures.md。
• 纹理（uncompressed-texture、texture-max-size）：使用 Compression Normal Quality，并调低 Max Size；必要时按平台分别设置（见下文的模式）。显式指定 Format 的覆盖设置会忽略 Compression，因此请将该 Format 设为 Automatic 或压缩格式。对于 DXT/ETC 格式的下载大小，启用 Use Crunch Compression 可以进一步缩小文件，但会损失一些质量。
• 音频（pcm-audio）：音乐和环境音使用 Vorbis，短音效使用 ADPCM；立体声没有额外价值时启用 Force To Mono。
• 资源和 StreamingAssets：Resources 文件夹中的所有内容都会随包发布，无论是否加载；Assets/StreamingAssets 会逐字节复制。移走不使用的内容。
• 网格、动画、光照贴图：对于 FBX/OBJ，使用 Model Importer Mesh Compression（glTF：缩减源文件，参见 gltf-heavy-geometry）；对动画片段启用动画压缩；如果光照贴图在 Textures 类别中占比最高，则在 Lighting 窗口调低 Max Lightmap Size 并启用 Lightmap Compression。
• 场景：从要构建的配置文件的 Scene List 中移除测试场景。
• 代码和引擎大小：如果原生库、.wasm 或托管 DLL 在列表中占比最高，请应用平台参考文档中的设置；裁剪级别和 link.xml 属于 unity-build-pipeline。
• 打包：平台参考文档涵盖播放器压缩、商店打包以及不得随包发布的调试文件夹。

5. 重新构建、比较并验证

1. 将构建输出到一个空文件夹中（旧文件夹或残留的调试文件夹会导致大小失真）。
2. 重新运行 build_report.py 和检查器；你处理过的类别大小必须有所下降。再次测量步骤 1 中受限的文件，并以数字报告前后大小。
3. 按玩家实际使用的方式启动构建版本，进入游戏，并检查缩减过的资源。平台参考文档会说明操作方法（Web 构建需要服务器）。如果无法运行目标平台，请为自己的平台构建并启动，然后说明你测试的平台。
4. 对于 CI，build_report.py build.log --budget-mb 400 会在超出预算时退出并返回 1；如果日志中没有完整的大小数据可供比较，也会如此。它检查的是未压缩总大小，因此如果限制针对的是发布文件，请单独检查该文件。

注意事项

• 纹理设置看起来没问题，但构建体积仍然很大 → 纹理位于 .glb/.gltf 模型中。运行检查器；references/gltf-textures.md 中提供了解决方法。
• 构建报告中的纹理远大于 .meta 设置所允许的大小 → Build Profiles 窗口的 Asset Import Overrides 将 Texture Compression 设为 Force Uncompressed（或 Force No Crunch）。这是检查器无法检测到的本地迭代捷径；发布构建前请清除这些设置 （Build Profiles 参考文档）。
• 要对同一文件夹中的多个模型运行 .gltf 修复 → gltf-transform 会按纹理插槽命名它写入的图像（baseColor_1.png），并覆盖已有文件，因此每个模型最终都会使用最后一个模型的纹理。检查器的 fix: 行会说明何时应先将模型移到单独的文件夹；请按提示操作。
• 将 glTF 图像移出后法线贴图看起来不对 → 导入时它们启用了 sRGB。除基础色、自发光和镜面光泽度贴图对之外，请关闭所有贴图的 sRGB（Color Texture）。
• LZ4HC 让 zip 变小了，但 Steam 补丁却变得很大 → Steam 会自行压缩下载内容，而 Unity 压缩后的玩家数据会将微小更改分散到许多数据块中。在 Steam 和 Android 上，请将 Compression Method 保持为 Default；请参阅平台参考文档。
• Web 构建体积是预期的好几倍 → 这是开发构建，Unity 不会压缩开发构建。
• Addressables 内容未出现在构建报告的资源列表中 → 本地组会构建为资源包，并复制到玩家的 StreamingAssets/aa 中；玩家构建报告不会列出其中的资源。请使用 Addressables Build Report 窗口。当前版本的 Addressables 会将内容构建到 Library/，因此残留的 Assets/StreamingAssets/aa 已过时，但仍会随构建发布；Addressables 更新日志建议将其删除 （更新日志）。
• 打包后的精灵出现 uncompressed-texture 警告 → Sprite Atlas 中的精灵会使用图集的设置发布；请检查图集。
• 降低 Max Size 后纹理看起来模糊 → 该纹理占用的屏幕像素超过了限制；请提高它的 Max Size，并降低不那么显眼的内容。
• 检查器报告模型是 Git LFS pointer → 克隆目录中只有指针文件；测量前请运行 git lfs pull。

模式：批量限制纹理大小（Editor 脚本）

请先提交更改：这会修改导入设置，而 diff 就是审查依据。将脚本放在任意 Editor 文件夹下。与检查器一样，它会跳过小纹理，因此像素艺术和 UI 图标会保留原有设置。

using UnityEditor;
using UnityEngine;

public static class TextureBudget
{
    const int MaxSize = 2048;
    const int MinEdgeToCompress = 1024;

    [MenuItem("Tools/Build Size/Compress Large Textures")]
    static void CompressLargeTextures()
    {
        AssetDatabase.StartAssetEditing();   // one reimport pass instead of one per texture
        try
        {
            foreach (string guid in AssetDatabase.FindAssets("t:Texture2D", new[] { "Assets" }))
            {
                string path = AssetDatabase.GUIDToAssetPath(guid);
                if (AssetImporter.GetAtPath(path) is not TextureImporter importer)
                    continue;   // sub-assets of models (glTFast) have no TextureImporter
                importer.GetSourceTextureWidthAndHeight(out int width, out int height);
                if (Mathf.Max(width, height) < MinEdgeToCompress)
                    continue;

                bool changed = false;
                if (importer.maxTextureSize > MaxSize) { importer.maxTextureSize = MaxSize; changed = true; }
                if (importer.textureCompression == TextureImporterCompression.Uncompressed)
                {
                    importer.textureCompression = TextureImporterCompression.Compressed;
                    changed = true;
                }
                if (changed)
                {
                    importer.SaveAndReimport();
                    Debug.Log($"Compressed {path}");
                }
            }
        }
        finally
        {
            AssetDatabase.StopAssetEditing();
        }
    }
}

这会修改默认设置，该设置适用于所有未单独覆盖的平台。若要设置单个平台，请使用 importer.GetPlatformTextureSettings("Android")，设置 overridden = true、 maxTextureSize 和 textureCompression，然后调用 importer.SetPlatformTextureSettings(settings)。

可选辅助工具

此技能仅依赖文件和 Editor 日志即可运行。安装以下工具后，可减少这些步骤：

• Unity CLI（unity，实验性）：通过保留日志进行构建（步骤 2），并使用 unity build run 启动上一次构建，包括在本地服务器上启动 Web 构建 （Unity CLI 文档）。

• Unity 官方 Agent 技能（Unity-Technologies/skills）： optimize-web 和 optimize-audio 会通过正在运行的 Editor 应用 Player 和音频设置， project-auditor-fixes 会运行 Project Auditor。请使用它们进行 Editor 端的更改，并在整个过程中保留此技能的测量与比较循环。 ## 资源

• scripts/check_unity_build_size.py --help：项目检查。使用 --json 供工具使用，使用 --strict 在出现警告时失败。

• scripts/build_report.py --help：Build Report 摘要；可使用 --top、--json、--budget-mb。

• references/gltf-textures.md：glTFast 内嵌图像、大小表格、两种修复方法以及大型几何体。

• Unity 手册：减小构建文件大小、保留文件夹名称、在构建中包含其他文件。

相关技能

• unity-build-pipeline：构建脚本、CI、脚本后端、托管代码裁剪、Addressables 设置。
• performance-optimization：运行时内存和帧时间。
• create-game-assets：在导入前制作尺寸合适的纹理。
• steam-publish / itch-publish：上传打包后的构建。