版本：3.0.x

迁移指南

本兼容层允许大部分 v2.3 业务代码在 v3.x 下零修改编译通过。所有兼容 API 均标记了 [Obsolete]，编译时会输出警告提示迁移到 v3 新接口。

启用兼容层

兼容代码默认不参与编译，需要手动添加编译宏才能启用：

Unity Editor：Edit → Project Settings → Player → Scripting Define Symbols，添加 YOOASSET_LEGACY_API

添加后重新编译即可生效。当所有业务代码已迁移到 v3 新接口后，移除该宏即可彻底关闭兼容层。

API 对照表（自动兼容）

1.1 枚举与状态

v2.3 写法	v3 新写法
`EOperationStatus.Succeed`	`EOperationStatus.Succeeded`
`EFileClearMode.ClearAllBundleFiles`	`"ClearAllBundleFiles"` (字符串)
`EPlayMode.HostPlayMode`	已移除（用 Options 类代替）

1.2 HandleBase

v2.3 写法	v3 新写法
`handle.LastError`	`handle.Error`
`await handle.Task`	`await handle`
`handle.GetDownloadStatus()`	已移除

1.3 SceneHandle

v2.3 写法	v3 新写法
`sceneHandle.UnSuspend()`	`sceneHandle.AllowSceneActivation()`
`sceneHandle.UnloadAsync()`	`sceneHandle.UnloadSceneAsync()`

1.4 RawFileHandle

v2.3 写法	v3 新写法
`rawHandle.GetRawFileData()`	`File.ReadAllBytes(rawHandle.GetRawFilePath())`
`rawHandle.GetRawFileText()`	`File.ReadAllText(rawHandle.GetRawFilePath())`

1.5 AssetHandle 实例化

v2.3 写法	v3 新写法
`handle.InstantiateSync(parent)`	`handle.InstantiateSync(new InstantiateOptions(...))`
`handle.InstantiateSync(parent, worldPositionStays)`	同上
`handle.InstantiateSync(position, rotation)`	同上
`handle.InstantiateSync(position, rotation, parent)`	同上
`handle.InstantiateAsync(parent, actived)`	`handle.InstantiateAsync(new InstantiateOptions(...))`
`handle.InstantiateAsync(parent, worldPositionStays, actived)`	同上
`handle.InstantiateAsync(position, rotation, actived)`	同上
`handle.InstantiateAsync(position, rotation, parent, actived)`	同上

1.6 DownloaderOperation

v2.3 写法	v3 新写法
`downloader.BeginDownload()`	`downloader.StartDownload()`
`downloader.DownloadFinishCallback = ...`	`downloader.DownloadCompleted += ...`
`downloader.DownloadUpdateCallback = ...`	`downloader.DownloadProgressChanged += ...`
`downloader.DownloadErrorCallback = ...`	`downloader.DownloadError += ...`
`downloader.DownloadFileBeginCallback = ...`	`downloader.DownloadFileStarted += ...`

注意：v2.3 的 DownloadError 委托名与 v3 的 DownloadError event 冲突，已重命名为 DownloadErrorDelegate。如果你的旧代码中直接引用了 DownloaderOperation.DownloadError 委托类型，需要改为 DownloadErrorDelegate。

1.7 ResourcePackage

v2.3 写法	v3 新写法
`package.InitializeAsync(parameters)`	`package.InitializePackageAsync(options)`
`package.DestroyAsync()`	`package.DestroyPackageAsync()`
`package.RequestPackageVersionAsync(bool, int)`	`package.RequestPackageVersionAsync(options)`
`package.UpdatePackageManifestAsync(version, timeout)`	`package.LoadPackageManifestAsync(options)`
`package.PreDownloadContentAsync(version, timeout)`	`package.PrefetchManifestAsync(options)`
`package.ClearCacheFilesAsync(mode, param)`	`package.ClearCacheAsync(options)`
`package.UnloadUnusedAssetsAsync(loopCount)`	`package.UnloadUnusedAssetsAsync(options)`
`package.IsNeedDownloadFromRemote(location)`	`package.GetDownloadSize(location) > 0`
`package.CheckLocationValid(location)`	`package.IsLocationValid(location)`
`package.GetAssetInfoByGUID(guid)`	`package.GetAssetInfoByGuid(guid)`
`package.CreateResourceDownloader(maxNum, retry)`	`package.CreateResourceDownloader(options)`
`package.CreateBundleDownloader(...)`	`package.CreateResourceDownloader(bundleOptions)`
`package.CreateResourceUnpacker(maxNum, retry)`	`package.CreateResourceUnpacker(options)`
`package.CreateResourceImporter(paths, maxNum, retry)`	`package.CreateResourceImporter(bundleImporterOptions)`

1.8 YooAssets 静态类

v2.3 写法	v3 新写法
`YooAssets.Initialized`	`YooAssets.IsInitialized`
`YooAssets.GetAllPackages()`	`YooAssets.GetPackages()`
`YooAssets.TryGetPackage(name)` 返回 null	`YooAssets.TryGetPackage(name, out pkg)`
`YooAssets.RemovePackage(package)` 传入实例	`YooAssets.RemovePackage(packageName)` 传入字符串
`YooAssets.SetOperationSystemMaxTimeSlice(ms)`	`YooAssets.SetAsyncOperationMaxTimeSlice(ms)`
`YooAssets.SetDownloadSystemUnityWebRequest(...)`	已移除
`YooAssets.StartOperation(gameAsyncOp)`	已移除

1.9 文件系统参数

v2.3 写法	v3 新写法
`params.FileSystemClass`	`params.FileSystemTypeName`
`CreateDefaultBuildinFileSystemParameters(decryptSvc, root)`	`CreateDefaultBuiltinFileSystemParameters(root)`
`CreateDefaultCacheFileSystemParameters(remoteSvc, decryptSvc, root)`	`CreateDefaultSandboxFileSystemParameters(remoteService, root)`
`CreateDefaultWebServerFileSystemParameters(webDecryptSvc, disableCache)`	`CreateDefaultWebServerFileSystemParameters(disableCache)`
`CreateDefaultWebRemoteFileSystemParameters(remoteSvc, webDecryptSvc, disableCache)`	`CreateDefaultWebRemoteFileSystemParameters(remoteService, disableCache)`
`FileSystemParametersDefine.XXX` 常量	`EFileSystemParameter.Xxx` 枚举
`IRemoteServices`	`IRemoteService`
`IManifestRestoreServices`	`IManifestDecryptor`
`EOverwriteInstallClearMode`	`EInstallCleanupMode`
`AddParameter(FileSystemParametersDefine.REMOTE_SERVICES, remoteSvc)`	自动包装为 `IRemoteService`
`AddParameter(FileSystemParametersDefine.MANIFEST_SERVICES, manifestSvc)`	自动包装为 `IManifestDecryptor`
`AddParameter(FileSystemParametersDefine.INSTALL_CLEAR_MODE, oldMode)`	自动转换为 `EInstallCleanupMode`

1.10 其他旧类型

v2.3 类型	v3 对应
`InitializeParameters` 及子类	`EditorSimulateModeOptions` 等 Options 类
`InitializationOperation`	`InitializePackageOperation`
`DestroyOperation`	`DestroyPackageOperation`
`UpdatePackageManifestOperation`	`LoadPackageManifestOperation`
`PreDownloadContentOperation`	`PrefetchManifestOperation`
`GameAsyncOperation`	已移除（用 `AsyncOperationBase`）
`ImportFileInfo`	`ImportBundleInfo`
`DownloaderFinishData`	`DownloadCompletedEventArgs`
`DownloadUpdateData`	`DownloadProgressChangedEventArgs`
`DownloadErrorData`	`DownloadErrorEventArgs`
`DownloadFileData`	`DownloadFileStartedEventArgs`
`DownloadStatus`	已移除

手动迁移项（无法兼容）

2.1 默认包裹快捷 API（已彻底移除）

v2.3 中 YooAssets.SetDefaultPackage() 及其关联的约 50 个静态快捷方法已在 v3 中完全移除，不提供兼容：

// v2.3 写法 -- 不再支持
YooAssets.SetDefaultPackage(package);
YooAssets.LoadAssetAsync<GameObject>("Assets/Prefabs/Hero.prefab");

// v3 写法 -- 必须通过 ResourcePackage 实例调用
var package = YooAssets.GetPackage("DefaultPackage");
package.LoadAssetAsync<GameObject>("Assets/Prefabs/Hero.prefab");

迁移建议：全局搜索 YooAssets.Load、YooAssets.GetAssetInfo、YooAssets.SetDefaultPackage 等调用，替换为 package.Xxx(...) 形式。

2.2 DownloadError 委托名冲突

v2.3 的 DownloaderOperation.DownloadError 委托类型与 v3 的 DownloadError event 同名，兼容层已将旧委托重命名为 DownloadErrorDelegate。

2.3 LoadSceneAsync 的 suspendLoad 参数语义反转

v2.3 的 LoadSceneAsync(..., bool suspendLoad, ...) 与 v3 的 LoadSceneAsync(..., bool allowSceneActivation, ...) 参数类型签名完全相同，仅参数名和语义相反（suspendLoad=true 等价于 allowSceneActivation=false）。由于方法签名冲突，无法通过兼容层自动处理。

// v2.3 写法
package.LoadSceneAsync("scene", LoadSceneMode.Single, LocalPhysicsMode.None, suspendLoad: true, 100);

// v3 写法 -- 注意 bool 语义反转
package.LoadSceneAsync("scene", LoadSceneMode.Single, LocalPhysicsMode.None, allowSceneActivation: false, 100);

2.4 ClearCacheFilesOperation 类型名冲突

v2.3 的 ClearCacheFilesOperation 与 v3 内部同名类冲突，无法提供兼容包装类。如果旧代码中显式引用了该类型名，需改为 ClearCacheOperation。通过 package.ClearCacheFilesAsync(...) 调用并用 var 接收返回值的写法不受影响。

2.5 UnloadAllAssetsOptions 写法变更

v2.3 是 class + 公有可变字段，v3 是 readonly struct + 构造函数。此场景极少出现。

2.6 文件系统参数迁移

解密服务接口重构（必须手动迁移）

v2.3 的 IDecryptionServices 和 IWebDecryptionServices 在 v3 中已拆分为多个专用接口：

v2.3	v3
`IDecryptionServices.LoadAssetBundle()`	`IBundleOffsetDecryptor` 或 `IBundleStreamDecryptor`
`IDecryptionServices.LoadAssetBundleAsync()`	同上
`IDecryptionServices.LoadAssetBundleFallback()`	`IBundleMemoryDecryptor`
`IDecryptionServices.ReadFileData()` / `ReadFileText()`	已移除
`IWebDecryptionServices`	已移除，无替代

兼容层保留了 IDecryptionServices、IWebDecryptionServices 及相关 DecryptFileInfo / DecryptResult 类型签名以避免编译错误，但不会自动转换为 v3 解密器。旧工厂方法中传入的 decryptionServices 参数会被忽略。

// v2.3 写法
var fsp = FileSystemParameters.CreateDefaultBuildinFileSystemParameters(myDecryptSvc);

// 兼容层编译通过，但 myDecryptSvc 不生效！
// 迁移方法：实现 IBundleOffsetDecryptor 等新接口，通过 EFileSystemParameter 添加
var fsp = FileSystemParameters.CreateDefaultBuiltinFileSystemParameters();
fsp.AddParameter(EFileSystemParameter.AssetbundleDecryptor, myNewDecryptor);

已移除的参数常量

以下 FileSystemParametersDefine 常量在 v3 中无稳定等价参数，兼容层保留了常量值但 v3 文件系统不会识别：

APPEND_FILE_EXTENSION — 已移除
DISABLE_CATALOG_FILE — 已移除
COPY_LOCAL_FILE_SERVICES — 已移除
RESUME_DOWNLOAD_RESPONSE_CODES — 已移除

旧内部文件系统类名

v2.3 中通过字符串引用的内部文件系统类名在 v3 中已变更：

v2.3 类名	v3 类名
`DefaultEditorFileSystem`	`EditorFileSystem`
`DefaultBuildinFileSystem`	`BuiltinFileSystem`
`DefaultCacheFileSystem`	`SandboxFileSystem`
`DefaultWebServerFileSystem`	`WebServerFileSystem`
`DefaultWebRemoteFileSystem`	`WebRemoteFileSystem`

如果旧代码中手写了类名字符串（如 new FileSystemParameters("YooAsset.DefaultCacheFileSystem", root)），需改为 v3 工厂方法或更新类名。

启用兼容层​

API 对照表（自动兼容）​

1.1 枚举与状态​

1.2 HandleBase​

1.3 SceneHandle​

1.4 RawFileHandle​

1.5 AssetHandle 实例化​

1.6 DownloaderOperation​

1.7 ResourcePackage​

1.8 YooAssets 静态类​

1.9 文件系统参数​

1.10 其他旧类型​

手动迁移项（无法兼容）​

2.1 默认包裹快捷 API（已彻底移除）​

2.2 DownloadError 委托名冲突​

2.3 LoadSceneAsync 的 suspendLoad 参数语义反转​

2.4 ClearCacheFilesOperation 类型名冲突​

2.5 UnloadAllAssetsOptions 写法变更​

2.6 文件系统参数迁移​

解密服务接口重构（必须手动迁移）​

已移除的参数常量​

旧内部文件系统类名​