📋 环境检查清单

在动手之前，先确认你的机器满足以下条件：

项目 要求 说明
Unity 版本 2021.3 LTS 或 2022.3 LTS 强烈推荐LTS，非LTS版本兼容性风险高
脚本后端 IL2CPP HybridCLR 依赖 IL2CPP，Mono 不可用
Visual Studio 2019/2022 + C++桌面开发工作负载 IL2CPP 编译需要 MSVC 工具链
.NET SDK .NET 6 或更高 HybridCLR 编译器工具链依赖
Git 已安装且在 PATH 中 UPM 通过 git URL 拉取插件

🔧 第一步：安装 Unity IL2CPP 模块

很多人装了 Unity 却没装 IL2CPP 模块，导致后面切换后端时报错。

操作步骤

  1. 打开 Unity Hub → 找到你安装的 Unity 版本
  2. 点击右侧齿轮图标 → Add modules
  3. 勾选目标平台的 IL2CPP 模块：
    • Windows: Windows Build Support (IL2CPP)
    • Android: Android Build Support + OpenJDK + Android SDK & NDK Tools
    • iOS/macOS: 默认包含 IL2CPP
  4. 点击 Install，等待完成

⚠️ 注意：如果你之前只装了 Mono 后端，这里必须补装 IL2CPP。安装完成后重启 Unity Hub 生效。

🔧 第二步：配置 Visual Studio C++ 环境

IL2CPP 会把 C# 转成 C++ 再编译，所以需要完整的 C++ 工具链。这是小白最容易忽略的一步。

操作步骤

  1. 打开 Visual Studio Installer
  2. 找到已安装的 VS 版本 → 修改
  3. 在”工作负载”页签勾选：使用 C++ 的桌面开发
  4. 在右侧”安装详细信息”中确认包含：
    • MSVC v143 生成工具
    • Windows 10/11 SDK
    • C++ CMake 工具
  5. 点击 修改，等待安装完成

验证方法

打开命令行执行：

1
2
cl
# 应输出 Microsoft (R) C/C++ Optimizing Compiler Version ...

如果提示找不到 cl，说明环境变量未配置，重启电脑或手动添加 VS 的 VC\Tools\MSVC\bin 到 PATH。

🔧 第三步：创建 Unity 项目并切换 IL2CPP

  1. Unity Hub → New Project → 选择 3D Core 模板
  2. 项目名称建议：HybridCLRDemo（避免中文路径）
  3. 进入项目后：Edit → Project Settings → Player
  4. 找到 Scripting Backend → 改为 IL2CPP
  5. 弹出提示框点确认，Unity 会重新导入脚本

⚠️ 切换后首次编译较慢（5-15分钟属正常），耐心等待控制台无报错即可。

验证 IL2CPP 是否生效

菜单栏 Edit → Project Settings → Player → Other Settings，确认 Scripting Backend 显示为 IL2CPP (C++)。

🔧 第四步：导入 HybridCLR 插件

推荐使用 UPM（Unity Package Manager）方式，版本管理最省心。

操作步骤

  1. 菜单栏 Window → Package Manager
  2. 点击左上角 + → Add package from git URL
  3. 输入以下地址（二选一）：
1
2
3
4
5
# GitHub（推荐，更新最快）
https://github.com/focus-creative-games/hybridclr_unity.git

# Gitee（国内网络不稳定时使用）
https://gitee.com/focus-creative-games/hybridclr_unity.git
  1. 等待 Unity 自动拉取并安装，控制台出现 hybridclr 相关日志即成功

验证安装

菜单栏应出现 HybridCLR 菜单项。如果没有，检查 Console 是否有 git clone 失败的网络错误。

🔧 第五步：运行 HybridCLR Installer

这一步至关重要！ 仅仅导入插件是不够的，Installer 会修改 Unity 编辑器底层的 IL2CPP 运行时，生成必要的数据文件。

操作步骤

  1. 菜单栏 HybridCLR → Installer
  2. 点击 Install 按钮
  3. 等待控制台输出类似以下信息：
    1
    2
    [HybridCLR] Install successfully!
    [HybridCLR] il2cpp has been modified.
  4. 确认 Library/HybridCLRData 目录已生成且包含文件

⚠️ 常见安装失败原因

现象 原因 解决
Install 按钮灰色 Unity 版本不兼容 切换到支持的 LTS 版本
报网络错误 git 仓库访问超时 换 Gitee 源或挂代理
报权限错误 Unity 安装在系统保护目录 以管理员身份运行 Unity
安装成功但目录为空 Installer 版本与插件不匹配 重新 Add package 后再 Install

💡 重要提醒：每次升级 HybridCLR 插件版本后，必须重新运行 Installer。否则底层运行时与新插件版本不一致，会导致各种诡异报错。

🔧 第六步：配置 HybridCLR Settings

  1. 菜单栏 HybridCLR → Settings
  2. 关键配置项说明：
配置项 推荐值 说明
Enable ✅ 勾选 总开关
HotUpdate Assemblies 暂留空 下一篇创建热更程序集后再填
AOT Metadata Supplement ✅ 勾选 启用泛型补充元数据，必开
Preserve Type Reference ✅ 勾选 防止代码裁剪误删热更引用的类型
  1. 点击 Save

✅ 环境验证：跑通空项目

完成以上所有步骤后，做一次完整构建验证：

  1. File → Build Settings → 选择目标平台（建议先用 Windows Standalone 验证）
  2. 点击 Build，选择输出目录
  3. 等待构建完成（首次 IL2CPP 构建约 3-8 分钟）
  4. 运行生成的 exe，确认能正常启动且无崩溃

如果构建成功且运行正常，恭喜你，HybridCLR 开发环境已就绪！

❓ 环境问题速查

Q: 切换 IL2CPP 后 Unity 一直卡在 Compiling Scripts？
A: 首次切换需要全量重编译，大项目可能耗时20分钟以上。若超过30分钟无进展，检查杀毒软件是否拦截了 cl.exe 进程。

Q: Installer 提示 “Unity version not supported”？
A: 查阅 HybridCLR 官方兼容列表。截至2025年，稳定支持 2020.3、2021.3、2022.3 LTS。2023.x 部分版本支持但需特定插件版本。

Q: Package Manager 添加 git URL 后无任何反应？
A: 确认 Git 已安装且在系统 PATH 中。命令行执行 git --version 验证。Windows 用户重装 Git 时务必勾选 “Add to PATH”。

Q: Library/HybridCLRData 目录存在但里面是空的？
A: Installer 未完整执行。删除该目录后重新运行 HybridCLR → Installer → Install。

下一篇预告：创建你的第一个热更新程序集，编写一个可以在运行时替换的 C# 脚本，并在编辑器和真机上验证热更效果。

说些什么吧！

waline