mobsakai/unity3d

Dockerised Unity Editor 镜像文档

镜像概述

Dockerised Unity Editor镜像是将Unity编辑器（Unity Editor）打包为Docker容器的标准化部署方案。通过容器化技术，解决传统Unity开发中环境配置复杂、跨平台依赖不一致、版本管理混乱等问题，提供隔离、可移植、版本固定的Unity运行环境，适用于自动化构建、持续集成/持续部署（CI/CD）及统一开发流程。

主要用途

• 游戏项目的自动化构建流程（Windows、macOS、Linux、Android、iOS等平台）
• CI/CD流水线集成，实现代码提交后自动编译、打包及测试
• 统一团队开发环境，避免"在我电脑上能运行"的环境依赖问题
• 多版本Unity项目的并行开发与隔离部署
• 服务器端Unity应用（如实时3D服务）的构建与运行

核心功能与特性

核心功能

• 容器化环境隔离：将Unity编辑器及其依赖（如Mono、.NET运行时、构建工具链）封装在容器中，避免与主机系统依赖冲突
• 版本固定与一致性：镜像内置特定版本的Unity编辑器，确保所有使用该镜像的环境运行相同版本，消除版本差异导致的构建问题
• 命令行自动化支持：支持通过Unity命令行接口（CLI）执行构建、导出、测试等操作，适配自动化脚本调用
• 跨平台可移植性：基于Linux基础镜像构建，可在任何支持Docker的Linux系统（如Ubuntu、CentOS）中运行，无需单独配置系统级依赖

特性优势

• 资源高效利用：通过Docker镜像分层机制，共享基础镜像层，减少多实例部署的磁盘占用
• 快速环境重置：容器停止后自动清理临时文件，避免残留配置影响下次运行
• 许可证灵活管理：支持挂载Unity个人版/专业版许可证文件，或通过命令行激活浮动许可证
• 扩展性强：可通过Dockerfile扩展添加项目特定依赖（如Android SDK、iOS构建工具）

使用场景与适用范围

典型使用场景

1. 游戏开发团队CI/CD流程
   集成至GitLab CI、Jenkins、GitHub Actions等平台，实现代码提交后自动触发Unity项目构建、打包并上传至测试服务器

2. 多版本Unity项目并行开发
   为不同Unity版本（如2019.x、2021.x、2023.x）的项目分别部署对应版本镜像，避免本地安装多版本Unity的冲突问题

3. 自动化测试与构建任务
   定时执行Unity项目的单元测试、场景加载测试，并生成构建报告，及时发现版本迭代中的兼容性问题

4. 教学与演示环境
   快速部署统一的Unity教学环境，学生无需手动安装Unity，通过容器即可运行指定版本编辑器进行学习或演示

5. 服务器端Unity应用构建
   针对需要在服务器运行的Unity应用（如实时渲染服务、3D模拟引擎），通过镜像完成构建并部署至云服务器

适用范围

• 中小型游戏开发团队（10人以上）的协作开发
• 需频繁进行版本构建和测试的Unity项目
• 采用敏捷开发或持续交付模式的游戏项目
• 对开发环境一致性要求高的企业级游戏项目
• 需在Linux服务器执行Unity构建任务的场景

使用方法与配置说明

前提条件

• 已安装Docker Engine（20.10+版本）及Docker Compose（可选，用于多容器编排）
• 具备Unity编辑器使用权限（需有效的Unity许可证，个人版/专业版均可）
• 主机系统需满足：Linux x86_64架构（推荐Ubuntu 20.04+或CentOS 8+），至少4GB内存及20GB磁盘空间

基础使用步骤

1. 获取镜像

从Docker Registry拉取指定版本镜像（假设镜像名为unity-editor，标签为Unity版本号，如2021.3.2f1）：

bash
docker pull unity-editor:2021.3.2f1

2. 基本运行命令

通过docker run启动容器，挂载本地Unity项目目录并执行构建任务：

bash
docker run -it --rm \
  -v /path/to/local/unity/project:/workspace/project \  # 挂载本地项目目录至容器内/workspace/project
  -v /path/to/unity/license:/workspace/license.ulf \   # 挂载Unity许可证文件（.ulf格式）
  -e UNITY_LOG_LEVEL=info \                            # 设置日志级别（error/warn/info/debug）
  unity-editor:2021.3.2f1 \                            # 使用的镜像及版本
  unity-editor -batchmode \                            # Unity命令行模式（无GUI）
               -projectPath /workspace/project \       # 指定项目路径
               -buildWindowsPlayer /workspace/project/Builds/Windows/Game.exe \  # 构建Windows平台可执行文件
               -quit \                                 # 构建完成后退出
               -logFile /workspace/project/build.log   # 日志输出至文件

3. Docker Compose配置（多项目/多任务场景）

创建docker-compose.yml文件，定义持久化卷、环境变量及服务依赖：

yaml
version: '3.8'
services:
  unity-builder:
    image: unity-editor:2021.3.2f1
    volumes:
      - ./projects:/workspace/projects  # 本地项目目录（可包含多个Unity项目）
      - ./licenses:/workspace/licenses  # 许可证文件目录（可存放多个版本许可证）
      - unity-cache:/root/.cache/unity  # 持久化Unity缓存（加速重复构建）
    environment:
      - UNITY_VERSION=2021.3.2f1
      - DEFAULT_BUILD_TARGET=Android    # 默认构建目标平台
      - LOG_LEVEL=info
    command: >
      sh -c "unity-editor -batchmode 
             -projectPath /workspace/projects/my-game 
             -buildAndroidPlayer /workspace/projects/my-game/Builds/Android 
             -quit -logFile /workspace/projects/my-game/build.log"

volumes:
  unity-cache:  # 命名卷，持久化Unity缓存数据

启动服务：

bash
docker-compose up

关键配置参数说明

环境变量

挂载目录建议

Unity命令行参数（核心构建命令）

容器内通过unity-editor命令调用Unity编辑器，支持所有官方命令行参数，常用构建相关参数：

• -batchmode：无GUI批处理模式（必须，容器内无图形界面）
• -projectPath <path>：指定Unity项目路径
• -build<Platform>Player <output-path>：构建目标平台可执行文件（如-buildAndroidPlayer）
• -exportPackage <assets-path> <output-package>：导出资源包
• -executeMethod <ClassName.MethodName>：执行项目中的C#静态方法（用于自定义构建逻辑）
• -quit：任务完成后退出编辑器
• -logFile <path>：将日志输出至指定文件（避免控制台输出乱码）
• -nographics：禁用图形渲染（进一步优化容器资源占用）

注意事项

1. Unity许可证激活：容器首次运行需激活Unity许可证，个人版可通过Unity Hub生成离线激活文件（.ulf）并挂载；专业版支持浮动许可证服务器，需配置-licenseServer参数指向服务器地址。
2. 构建平台依赖：部分平台（如iOS）构建需额外依赖（如Xcode工具链），需使用包含对应工具链的扩展镜像（如unity-editor:2021.3.2f1-ios）。
3. 性能要求：Unity构建任务对CPU和内存消耗较高，建议主机配置至少4核CPU及8GB内存，构建大型项目时可通过--cpus和--memory参数限制容器资源占用。
4. 权限问题：挂载目录需确保Docker用户有读写权限，避免因权限不足导致构建失败（可通过-u $(id -u):$(id -g)参数指定容器内用户ID）。

常见问题与解决方法

• 许可证无效：检查许可证文件路径是否正确挂载，或确认许可证未过期；个人版许可证仅支持单设备激活，需确保容器内未同时运行多个实例。
• 构建失败提示"缺少依赖"：确认使用的镜像包含目标平台构建工具链（如Android构建需Android SDK，可选择带sdk标签的镜像变体）。
• 项目资源导入缓慢：挂载并持久化PROJECT_CACHE_DIR目录，缓存已导入资源；或增加容器内存分配（--memory=16g）。
• 容器启动后立即退出：检查unity-editor命令是否添加-batchmode和-quit参数，无任务时容器会自动退出，需确保构建命令正确执行。