CDN Release FileMapping 使用文档

安装配置 UOS Launcher

参考 Launcher 教程，安装 Launcher 后，关联 UOS APP

注意: 请务必确认在进行后续教程之前，已经成功完成了 Launcher 教程的安装步骤，否则可能导致后续接入无法顺利进行。

概述

使用 CDN Release 资源中的 CDN映射 来直接获取 CDN地址， 它通过资源桶 ID 和 Badge/Release ID 来获取文件映射关系，并提供便捷的方法来获取文件的 CDN 下载链接。

API 说明

InitializeAsync

初始化并获取文件映射。

public static async Task<bool> InitializeAsync(string bucketId, string badgeName, string releaseId)

参数：

参数名	类型	说明
bucketId	string	资源桶 ID
badgeName	string	Badge 名称，如果和 releaseId 同时为空，默认使用 latest
releaseId	string	Release ID，有传值的话会优先使用

返回值：

• Task<bool>: 初始化是否成功

注意事项：

• 必须先设置 UOS App ID（通过 UOS Launcher）
• 如果已经初始化过，会直接返回 true
• 初始化失败会在控制台输出警告信息

示例：

// 使用 Badge 初始化（默认使用 latest）
bool success = await CdnDownloadUtils.InitializeAsync("your-bucket-id", "", "");

// 使用指定 Badge 初始化
bool success = await CdnDownloadUtils.InitializeAsync("your-bucket-id", "production", "");

// 使用 Release ID 初始化
bool success = await CdnDownloadUtils.InitializeAsync("your-bucket-id", "", "release-123456");

---

GetDownloadMapping

获取资源映射关系表。

public static Dictionary<string, string> GetDownloadMapping()

返回值：

• Dictionary<string, string>: 文件名到文件路径的映射表
• 如果未初始化，返回 null

示例：

var mapping = CdnDownloadUtils.GetDownloadMapping();
if (mapping != null)
{
    foreach (var kvp in mapping)
    {
        Debug.Log($"文件名: {kvp.Key}, 路径: {kvp.Value}");
    }
}

---

GetDownloadUrl

获取文件下载链接。

public static string GetDownloadUrl(string fileName)

参数：

参数名	类型	说明
fileName	string	文件名

返回值：

• string: 完整的 CDN 下载链接
• 如果未初始化或文件不存在，返回空字符串

示例：

string url = CdnDownloadUtils.GetDownloadUrl("config.json");
if (!string.IsNullOrEmpty(url))
{
    Debug.Log($"下载链接: {url}");
    // 使用 UnityWebRequest 或其他方式下载文件
}

---

TryGetDownloadUrl

尝试获取文件下载链接（安全版本）。

public static bool TryGetDownloadUrl(string fileName, out string downloadUrl)

参数：

参数名	类型	说明
fileName	string	文件名
downloadUrl	out string	输出参数，下载链接

返回值：

• bool: 是否成功获取下载链接

示例：

if (CdnDownloadUtils.TryGetDownloadUrl("assets.zip", out string url))
{
    Debug.Log($"下载链接: {url}");
    // 开始下载
}
else
{
    Debug.LogWarning("获取下载链接失败");
}

---

ClearCache

清除缓存，重置所有状态。

public static void ClearCache()

说明：

• 清除后会重置初始化状态
• 下次使用需要重新调用 InitializeAsync

示例：

CdnDownloadUtils.ClearCache();
// 需要重新初始化
await CdnDownloadUtils.InitializeAsync("new-bucket-id", "staging", "");

完整使用示例

using UnityEngine;
using Unity.UOS.Common;

public class CdnDownloadExample : MonoBehaviour
{
    async void Start()
    {
        // 1. 初始化
        bool success = await CdnDownloadUtils.InitializeAsync(
            "my-bucket-id",
            "production",
            ""
        );

        if (!success)
        {
            Debug.LogError("CDN 初始化失败");
            return;
        }

        // 2. 获取单个文件下载链接
        string fileUrl = CdnDownloadUtils.GetDownloadUrl("game-config.json");
        Debug.Log($"配置文件下载链接: {fileUrl}");

        // 3. 安全获取下载链接
        if (CdnDownloadUtils.TryGetDownloadUrl("assets-bundle.zip", out string assetUrl))
        {
            // 使用 UnityWebRequest 下载资源
            // StartCoroutine(DownloadFile(assetUrl));
        }

        // 4. 获取所有文件映射
        var mapping = CdnDownloadUtils.GetDownloadMapping();
        Debug.Log($"共有 {mapping.Count} 个文件可下载");

        // 5. 清除缓存（可选）
        CdnDownloadUtils.ClearCache();
    }
}

注意事项

1. Launcher设置：确保在使用前已正确配置UOS Launcher
2. 初始化顺序：必须先调用 InitializeAsync 并成功后，才能调用其他方法
3. 网络请求：初始化过程涉及网络请求，建议在合适的时机调用（如游戏启动时）
4. 错误处理：初始化失败时会在控制台输出警告，请注意查看日志