游戏引擎 / 系统课时

排查发布包中的路径问题

排查发布包中的路径问题

同一份 Unity 项目在编辑器里能读取配置、保存进度,发布后却提示文件不存在或访问被拒绝,原因往往是打包位置、文件系统与权限发生了变化。本课用一段最小探针区分包内读取和用户数据写入,再按证据修复并实机复测。

学习目标

  • 区分 Unity 资源路径、包内只读目录和用户可写目录。
  • 用目标平台的日志和最小脚本定位读取或写入失败。
  • 修复路径、打包或权限问题,并验证更新后仍可正常读写。

先确认失败发生在哪里

不要根据编辑器 Console 里的成功记录判定发布包也能工作。先在目标设备运行 Development Build,记录失败时的场景、操作、资源文件名、实际路径或 URI、调用的 API,以及异常或请求错误。复现时尽量保持构建版本和设备一致。

FileNotFoundException 常见于文件未打入包、大小写不一致或错误拼接路径;UnauthorizedAccessException 更偏向写入位置和权限;UnityWebRequest 失败则需进一步检查 URI、包内内容或 Web 服务器。它们是排查方向,不是仅凭异常名就能确认的根因。

尤其不要将编辑器中的 Assets/... 当作玩家设备上的实际文件夹,也不要依赖进程当前工作目录。AssetDatabase 属于编辑器 API,不能充当运行时资源加载方案。

选择正确的资源入口与目录

入口 适合放什么 发布包中的边界
Resources.Load 随包构建、按资源名加载的 Unity 资源 使用 Resources 内相对路径且不带扩展名,不是普通文件路径
Application.streamingAssetsPath 原样随包发布的 JSON、视频等文件 只读;Android 位于 APK/JAR 中,WebGL 对应 HTTP URL
Application.persistentDataPath 玩家存档、设置、下载后缓存 可读写,但实际目录随平台和应用标识变化
Application.dataPath 应用安装数据位置 不应当作用户存档目录

当需要直接读取随包文本时,使用 StreamingAssets。桌面端通常可把路径转换为 file URI,Android 和 WebGL 则必须按其 URI 访问;统一通过 UnityWebRequest 可以避免把 APK 当成普通目录。存档始终写入 persistentDataPath,不能反向写进包内资源。

发布包只读资源和用户可写数据的跨平台访问关系

用最小脚本区分读包与写盘

在项目内创建 Assets/StreamingAssets/config.json,内容保持如下。将脚本保存为 BuildPathProbe.cs,挂到启动场景中的一个启用对象上,再把该场景纳入构建并运行。

json
{"region":"test","maxRetries":2}
csharp
using System;
using System.Collections;
using System.IO;
using UnityEngine;
using UnityEngine.Networking;

public sealed class BuildPathProbe : MonoBehaviour
{
    private IEnumerator Start()
    {
        string location = Application.streamingAssetsPath.TrimEnd('/', '\\') + "/config.json";
        // 普通文件路径转换为 URI;Android 和 WebGL 已返回可请求的 URI。
        string uri = location.Contains("://")
            ? location
            : new UriBuilder("file", "", -1, Path.GetFullPath(location)).Uri.AbsoluteUri;

        using (UnityWebRequest request = UnityWebRequest.Get(uri))
        {
            yield return request.SendWebRequest();
            if (request.result != UnityWebRequest.Result.Success)
            {
                Debug.LogError("Packaged read: FAIL " + request.error);
                yield break;
            }
            Debug.Log("Packaged read: " + request.downloadHandler.text);
        }

        // 用独立测试文件验证可写区,不接触真实玩家存档。
        if (string.IsNullOrEmpty(Application.persistentDataPath))
        {
            Debug.LogError("Writable data: FAIL no persistentDataPath");
            yield break;
        }
        string path = Path.Combine(Application.persistentDataPath, "path-probe.txt");
        try
        {
            File.WriteAllText(path, "ok");
            Debug.Log("Writable data: " + File.ReadAllText(path));
        }
        catch (Exception e)
        {
            Debug.LogError("Writable data: FAIL " + e.GetType().Name);
        }
    }
}

预期输出(上述配置文件存在、目标平台支持持久目录且读写成功时):

text
Packaged read: {"region":"test","maxRetries":2}
Writable data: ok

第一行失败,优先核对 StreamingAssets 的文件名、大小写和构建产物;第二行失败,检查 persistentDataPath 是否有效、存储空间和系统权限。失败时日志会显示 FAIL 及具体错误,而不是上述成功输出。WebGL 还需通过服务器部署测试,并在刷新页面后另行验证存档持久化。

按根因修复并回归

  • 资源没进包:核对 StreamingAssets 的实际层级;若用 Resources,确认文件处于资源目录且加载名不含扩展名。使用 Addressables 时另查构建的内容、目录与地址键,不能把项目路径直接传给加载器。
  • 平台路径不同:不要对 Android 的 APK/JAR URI 使用 File.ReadAllText,也不要用文件系统的 Path.Combine 去拼接 HTTP URL;按资源 API 的语义传入路径或 URI。
  • 写入失败:把配置默认值留在包内,把用户改动和存档写到可写目录;不要向 StreamingAssets 或 Application.dataPath 回写。
  • 只在某些设备失败:复核大小写、特殊字符、空间不足、WebGL 服务器资源是否上传以及跨域设置;保存请求 URI 和错误日志作为证据。

修复后至少进行一次全新安装、一次保留旧数据的覆盖安装,并在关闭与重启客户端后重复读取和保存。验收依据是目标设备上的实际结果,而不是编辑器能够找到相同文件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查发布包中的路径问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通