10-01-实战-环境搭建与集成

实战-环境搭建与集成

篇章 ：10-实战篇-从零搭建 状态 ：已完成 阅读时间：约 20 分钟

---

一、引言

1.1 本章在系列中的定位

从本章开始，我们进入实战篇 。前面 9 章已系统讲解了 YooAsset 的认知、原理、架构、源码与核心技术，本章和后续章节将通过可操作的步骤带你从零搭建一个完整的 YooAsset 项目。

实战篇的特点是：

• 步骤具体到"点哪个菜单、敲哪行命令"
• 配以可直接运行的代码
• 强调工程实践（CI/CD、监控、灰度）

1.2 本章要解决的核心问题

• 如何在 Unity 项目中安装 YooAsset？
• Unity 版本与 YooAsset 版本如何匹配？
• 一个标准的 YooAsset 项目目录结构是什么样的？
• 第一个 YooAsset Hello World 怎么跑起来？

1.3 阅读前置要求

• 已安装 Unity 2022 LTS 或更高版本
• 熟悉 Unity 编辑器基本操作
• 了解 Git 基本使用
• 拥有 GitHub 账号（推荐）

---

二、UPM 安装 YooAsset

2.1 通过 UPM Git URL 安装（推荐）

步骤详解

步骤 1：打开 Unity 编辑器

启动 Unity，打开你的项目。

步骤 2：打开 Package Manager

菜单栏：Window → Package Manager

步骤 3：添加 Git URL

点击左上角 + 按钮 → 选择 Add package from git URL

步骤 4：输入 YooAsset 的 Git URL

https://github.com/tuyoogame/YooAsset.git

或者使用指定版本：

https://github.com/tuyoogame/YooAsset.git#v2.2.4

步骤 5：等待安装完成

首次安装约需 1-3 分钟（取决于网络）。安装完成后，Unity 会自动：

• 拉取 YooAsset 的 C# 源码
• 生成 .meta 文件
• 触发 Library 重新生成

验证安装

安装成功后，应能在以下位置看到 YooAsset：

Project 视图
└── Packages/
    └── manifest.json
        └── "com.yoozoo.yooasset": "https://github.com/tuyoogame/YooAsset.git"

菜单栏应出现 YooAsset 菜单：

菜单栏
├── File
├── Edit
├── ...
└── YooAsset  ← 看到这个说明安装成功
    ├── Build
    ├── Create
    └── ...

2.2 通过 UPM tarball 安装（离线场景）

如果网络受限，可以下载 Release 包后通过 tarball 安装：

步骤 1：下载 Release

访问 github.com/tuyoogame/Y... .tar.gz 包。

步骤 2：本地安装

Package Manager → + → Add package from tarball → 选择下载的 .tar.gz 文件。

2.3 手动导入（不推荐）

下载 Release 的 .zip 包，解压后放到项目的 Packages/com.yoozoo.yooasset/ 目录下。

Assets/  (不要放到这里)
└── ...
Packages/
└── com.yoozoo.yooasset/  ← 放这里
    ├── package.json
    ├── Runtime/
    ├── Editor/
    └── ...

2.4 安装常见问题

问题	原因	解决方案
安装超时	网络问题	改用国内镜像或挂代理
版本冲突	依赖不兼容	删除 Library/PackageCache/ 后重试
编辑器报错	Unity 版本不兼容	升级到 Unity 2022 LTS
菜单不显示	安装未完成	等待 Library 重新生成完成

---

三、版本选择

3.1 Unity 版本兼容性

YooAsset 支持的 Unity 版本范围：

Unity 版本	YooAsset 支持	推荐度
2019.4 LTS	✅	★★★
2020.3 LTS	✅	★★★★
2021.3 LTS	✅	★★★★
2022.3 LTS	✅	★★★★★（推荐）
2023.x	✅	★★★★
6000.x (Unity 6)	✅	★★★★

推荐 ：Unity 2022.3 LTS，是当下最稳定的 LTS 版本。

3.2 YooAsset 版本选择

3.2.1 版本发布节奏

YooAsset 由 tuyoogame 团队维护，发版节奏：

• 主版本（如 v2.x）：大改，可能有 Breaking Change
• 次版本（如 v2.2.x）：新功能，向后兼容
• 修订版本（如 v2.2.4）：Bug 修复

3.2.2 选版本原则

项目阶段	推荐版本
新项目立项	最新稳定版（v2.2.x）
在研项目	当前使用的稳定版（不轻易升级）
长期维护	LTS 标签的版本
实验性需求	最新主版本（接受 Breaking Change）

3.2.3 升级策略

YooAsset 的升级通常很简单（API 稳定性高），但仍建议：

1. 先在测试分支升级
2. 跑通回归测试
3. 小流量灰度
4. 全量发布

3.3 依赖检查

YooAsset 的核心依赖极少，主要包括：

{
  "dependencies": {
    "com.unity.scriptablebuildpipeline": "1.21.5",  // 自动包含
    "com.unity.modules.imgui": "1.0.0",
    "com.unity.modules.ui": "1.0.0"
  }
}

可选依赖：

• com.unity.nuget.newtonsoft-json（用于 JSON 序列化）
• com.unity.scriptablebuildpipeline（构建时使用，Unity 自带）

---

四、项目结构准备

4.1 推荐的目录结构

MyGame/
├── Assets/
│   ├── Art/                # 美术资源
│   │   ├── Characters/     # 角色
│   │   ├── Environments/   # 场景
│   │   ├── UI/             # UI 资源
│   │   ├── Effects/        # 特效
│   │   └── Audio/          # 音频
│   ├── Configs/            # 配置表
│   │   ├── Character.json
│   │   ├── Skill.json
│   │   └── Item.json
│   ├── Scenes/             # 场景
│   │   ├── Boot.unity
│   │   ├── MainCity.unity
│   │   └── Battle.*.unity
│   ├── Scripts/            # 业务代码
│   │   ├── Common/
│   │   ├── Battle/
│   │   ├── UI/
│   │   └── Network/
│   ├── Startup/            # 首包资源（关键）
│   │   ├── UI/
│   │   │   ├── Logo.png
│   │   │   └── Loading.unity
│   │   └── Scripts/
│   │       └── GameLauncher.cs
│   ├── YooAsset/           # YooAsset 配置
│   │   ├── PackageSettings.asset
│   │   ├── GroupSettings/
│   │   │   ├── DefaultPackage.asset
│   │   │   ├── ActivityPackage.asset
│   │   │   └── DLCPackage.asset
│   │   └── BuildScript.cs
│   └── Resources/          # 首包必要（YooAsset 引导）
│       └── YooAssetConfig.json
│
├── ProjectSettings/        # Unity 项目设置
├── Packages/
│   └── manifest.json
└── ...

4.2 YooAsset 配置目录详解

4.2.1 PackageSettings.asset

全局配置，存放在 Assets/YooAsset/ 目录下，记录：

• 全局 PlayMode
• 默认 CDN URL
• 默认加密配置
• 默认压缩配置

4.2.2 GroupSettings/

每个 Group 一个配置文件：

// DefaultPackage.asset
public class YooAssetPackageConfig
{
    public string PackageName = "DefaultPackage";
    public string PackageVersion = "1.0.0";
    public EPlayMode DefaultPlayMode = EPlayMode.HostPlayMode;
    public string HostServerURL = "https://res-cdn.example.com/v1/";
}

4.2.3 BuildScript.cs

构建脚本，定义如何打包：

public class GameBuildScript
{
    [MenuItem("YooAsset/Build")]
    public static void Build()
    {
        var buildParams = new BuildParameters
        {
            BuildOutputRoot = "D:/Builds/MyGame",
            BuildVersion = PlayerSettings.bundleVersion,
            BuildTarget = BuildTarget.Android,
            BuildPipeline = EBuildPipeline.ScriptableBuildPipeline,
            CompressOption = ECompressOption.LZ4,
            CopyToStreamingAssets = true
        };
        
        var pipeline = new ScriptableBuildPipeline();
        pipeline.Build(buildParams);
    }
}

4.3 Resources 与 StreamingAssets 的取舍

4.3.1 Resources/

YooAsset 启动需要读取本地清单，必须有一个 Resources 中的配置：

Resources/
└── YooAssetConfig.json

内容示例：

{
  "DefaultPackageName": "DefaultPackage",
  "DefaultPlayMode": "HostPlayMode",
  "HostServerURL": "https://res-cdn.example.com/v1/",
  "FallbackHostServerURL": "https://res-cdn-bj.example.com/v1/"
}

4.3.2 StreamingAssets/

构建时，YooAsset 会把首包资源拷贝到 StreamingAssets/，包括：

• 内置 Bundle 文件
• 内置 Manifest

注意 ：StreamingAssets 的文件大小会计入包体，要严格控制。

---

五、第一个 YooAsset 项目

5.1 创建 Package

步骤 1：打开 YooAsset 创建菜单

YooAsset → Create → Package

步骤 2：选择存储位置

选择 Assets/YooAsset/GroupSettings/DefaultPackage.asset

步骤 3：配置 Package

PackageName:        DefaultPackage
PackageVersion:     1.0.0
DefaultPlayMode:    HostPlayMode
HostServerURL:      https://res-cdn.example.com/v1/

5.2 创建 Group

步骤 1：在 Package 下创建 Group

YooAsset → Create → Group

步骤 2：配置 Group

GroupName:        Main
GroupDesc:        主包资源
PackRule:         ByFile  // 按文件打包
CompressOption:   LZ4

5.3 创建 Collector

步骤 1：在 Group 下创建 Collector

步骤 2：配置 Collector

CollectorName:     MainCollector
CollectFolder:     Assets/Art
SearchPattern:     *
PackToBundle:      Auto
AddressMode:       Location

步骤 3：测试收集

YooAsset → Collect Asset

应该看到：

• 收集到 N 个资源
• 预计生成 M 个 Bundle

5.4 第一次打包

步骤详解

步骤 1：打开构建窗口

YooAsset → Build AssetBundle

步骤 2：配置构建参数

BuildTarget:       Android  // 首次建议 Android/Windows
BuildPipeline:     ScriptableBuildPipeline
CompressOption:    LZ4
EncryptionOption:  None     // 首次测试不加密
CopyToStreaming:   true     // 自动拷贝到 StreamingAssets
OutputPath:        D:/Builds/MyGame

步骤 3：执行构建

点击 Build 按钮，等待完成。

构建结果

构建成功后，输出目录结构：

D:/Builds/MyGame/
├── BuildReport.html       ← 构建报告
├── BuildLog.txt
└── Android/
    ├── PackageManifest_1.0.0.bytes
    ├── PackageManifest_1.0.0.hash
    └── bundles/
        ├── bundle_01
        ├── bundle_02
        └── ...

验证清单

在 Unity 编辑器中查看 Assets/StreamingAssets/yooasset/：

StreamingAssets/
└── yooasset/
    ├── DefaultPackage/
    │   ├── PackageManifest_1.0.0.bytes
    │   └── ...
    └── bundles/
        ├── bundle_01
        └── ...

5.5 第一个加载测试

编辑器测试

步骤 1：创建测试脚本

using UnityEngine;
using YooAsset;

public class YooAssetHelloWorld : MonoBehaviour
{
    async void Start()
    {
        // 1. 初始化
        var initOp = YooAssets.InitializeAsync();
        await initOp.Task;
        
        if (initOp.Status != EOperationStatus.Succeed)
        {
            Debug.LogError($"初始化失败: {initOp.Error}");
            return;
        }
        
        // 2. 加载一个 Sprite
        var spriteOp = YooAssets.LoadAssetAsync<Sprite>("Assets/Art/UI/Icon.png");
        await spriteOp.Task;
        
        if (spriteOp.Status == EOperationStatus.Succeed)
        {
            Debug.Log($"加载成功: {spriteOp.Result.name}");
            // 显示在 UI 上
            GetComponent<SpriteRenderer>().sprite = spriteOp.Result;
        }
    }
}

步骤 2：配置 PlayMode

YooAsset → PlayMode → EditorPlayMode（编辑器内使用，无需服务器）

步骤 3：运行场景

点击 Play 按钮，应该能看到 Sprite 加载成功。

常见运行错误

错误	原因	解决
初始化失败	Package 名错误	检查 PackageSettings
资源找不到	Address 错误	运行 Collect Asset 重新生成
Bundle 加载失败	未构建	重新 Build
PlayMode 错	未设置 PlayMode	在 PlayMode 菜单中设置

---

六、CI/CD 集成

6.1 命令行构建

YooAsset 支持纯命令行构建：

# Windows
Unity.exe -batchmode -quit -projectPath <project> -executeMethod YooAsset.Editor.BuildPipeline.Build

public class BuildPipeline
{
    public static void Build()
    {
        var buildParams = new BuildParameters
        {
            BuildOutputRoot = System.Environment.GetEnvironmentVariable("BUILD_OUTPUT") ?? "Builds",
            BuildVersion = System.Environment.GetEnvironmentVariable("BUILD_VERSION") ?? "1.0.0",
            BuildTarget = (BuildTarget)Enum.Parse(typeof(BuildTarget), 
                System.Environment.GetEnvironmentVariable("BUILD_TARGET") ?? "Android"),
        };
        
        new ScriptableBuildPipeline().Build(buildParams);
    }
}

6.2 Jenkins 集成

// Jenkinsfile
pipeline {
    agent any
    
    stages {
        stage('Build') {
            steps {
                sh '''
                    export BUILD_OUTPUT=${WORKSPACE}/Builds
                    export BUILD_VERSION=${BUILD_NUMBER}
                    export BUILD_TARGET=Android
                    Unity -batchmode -quit -projectPath . -executeMethod YooAsset.Editor.BuildPipeline.Build
                '''
            }
        }
        stage('Upload') {
            steps {
                sh '''
                    python upload.py $BUILD_OUTPUT $BUILD_VERSION
                '''
            }
        }
    }
}

---

七、调试技巧

7.1 编辑器调试

YooAsset 提供 Editor 模式下的调试窗口：

YooAsset → Debug Window

可以看到：

• 当前所有 Package 的状态
• 加载中的操作
• 已加载的资源
• 内存占用

7.2 日志配置

public class LogConfig
{
    public static void Setup()
    {
        YooAssetLogger.LogHandler = (level, message) =>
        {
            switch (level)
            {
                case ELogLevel.Error:
                    Debug.LogError($"[YooAsset] {message}");
                    break;
                case ELogLevel.Warning:
                    Debug.LogWarning($"[YooAsset] {message}");
                    break;
                default:
                    Debug.Log($"[YooAsset] {message}");
                    break;
            }
        };
    }
}

7.3 常见调试场景

场景 1：资源找不到

// 开启详细日志
YooAssetLogger.LogLevel = ELogLevel.Debug;

// 加载时打印
Debug.Log($"尝试加载: {location}");
var op = YooAssets.LoadAssetAsync<Sprite>(location);
await op.Task;
Debug.Log($"加载结果: status={op.Status}, error={op.Error}");

场景 2：构建失败

查看 BuildLog.txt，通常包含：

• 哪个资源报错
• 依赖关系
• Bundle 划分建议

---

八、总结

8.1 本章要点回顾

• 安装方式：UPM Git URL 是最推荐的安装方式
• 版本选择：Unity 2022 LTS + YooAsset 最新稳定版
• 目录结构：Assets/YooAsset 是配置根目录
• Hello World：第一次跑通需要 Package → Group → Collector → Build → Load 五个步骤

8.2 与前后章节的关联

• 前章：09 章解决了部署与生态问题
• 本章：从零搭建 YooAsset 项目
• 后章：10-02 将对比 YooAsset 与原生 AssetBundle

8.3 实践建议

1. 优先用 UPM Git URL 安装：便于升级和版本管理
2. 使用 Unity 2022 LTS：当前最稳定的 LTS 版本
3. 首包要严格控制：只放启动必需的资源
4. 每次配置改动都重新构建：避免缓存导致的奇怪问题
5. 保留构建日志：便于排查问题

---

上一篇 ：UOS CDN与服务器部署(../09-生态篇-集成与协同/09-04-生态-UOS CDN与服务器部署.md) 下一篇 ：Unity 原生 AssetBundle 实战