101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
# VContainer（Unity DI）文档笔记
|
||
|
||
来源: https://vcontainer.hadashikick.jp/
|
||
记录时间: 2026-02-11
|
||
|
||
## 一句话总结
|
||
|
||
VContainer 是面向 Unity 的高性能 DI 容器，核心是 `LifetimeScope + 明确生命周期 + PlayerLoop EntryPoint`，兼顾性能、可维护性与可测试性。
|
||
|
||
## 核心概念
|
||
|
||
- `LifetimeScope` 是组合根（Composition Root），在这里集中做注册。
|
||
- 依赖推荐通过构造函数注入，业务入口可以使用纯 C# 类，不必全部依赖 `MonoBehaviour`。
|
||
- 容器不可变（Immutable），强调线程安全和稳定性。
|
||
|
||
## 安装方式
|
||
|
||
- OpenUPM（推荐）
|
||
- 命令: `openupm add jp.hadashikick.vcontainer`
|
||
- UPM Git URL
|
||
- `"jp.hadashikick.vcontainer": "https://github.com/hadashiA/VContainer.git?path=VContainer/Assets/VContainer#1.17.0"`
|
||
- 手动导入 `.unitypackage`
|
||
- 官方要求: Unity 2018.4+
|
||
|
||
## Hello World 最小流程
|
||
|
||
1. 新建继承 `LifetimeScope` 的组件（如 `GameLifetimeScope`）。
|
||
2. 在 `Configure(IContainerBuilder builder)` 中注册依赖。
|
||
3. 把该 `LifetimeScope` 挂到场景中的 GameObject。
|
||
4. 通过构造函数自动注入依赖。
|
||
5. 需要接入 Unity 生命周期时，使用 marker interface（例如 `ITickable`）。
|
||
|
||
## 生命周期（Lifetime）
|
||
|
||
- `Singleton`
|
||
- 全容器共享一个实例。
|
||
- 同一容器内同类型不能重复注册。
|
||
- `Transient`
|
||
- 每次 `Resolve` 新建实例。
|
||
- `Scoped`
|
||
- 每个 `LifetimeScope` 一份实例。
|
||
- 子 Scope 与父 Scope 可以拥有各自实例。
|
||
- Scope 销毁时会释放引用并调用已注册对象的 `IDisposable`。
|
||
|
||
父子 Scope 规则要点：
|
||
|
||
- 子 Scope 找不到注册时会向父 Scope 查找。
|
||
- 父子都注册了同类型时，优先使用“最近的 Scope”。
|
||
- 注意：如果仅销毁 `LifetimeScope`，注册为 `Lifetime.Scoped` 的 `MonoBehaviour` 不会自动销毁；需要通过层级管理或显式释放策略处理。
|
||
|
||
## 常见注册写法
|
||
|
||
- 注册具体类
|
||
- `builder.Register<ServiceA>(Lifetime.Singleton);`
|
||
- 以接口注册
|
||
- `builder.Register<IServiceA, ServiceA>();`
|
||
- 多接口注册
|
||
- `builder.Register<ServiceA>(Lifetime.Singleton).As<IServiceA, IInputPort>();`
|
||
- 自动注册已实现接口
|
||
- `builder.Register<ServiceA>(Lifetime.Singleton).AsImplementedInterfaces();`
|
||
- 同时保留接口与自身类型
|
||
- `builder.Register<ServiceA>(Lifetime.Singleton).AsImplementedInterfaces().AsSelf();`
|
||
- 实例注册
|
||
- `builder.RegisterInstance(obj);`
|
||
- 注意：`RegisterInstance` 默认等同单例，但实例生命周期不由容器托管（不会自动 `Dispose`、不会自动做方法注入）。
|
||
|
||
## Plain C# EntryPoint（推荐实践）
|
||
|
||
- 使用 `builder.RegisterEntryPoint<T>()` 把纯 C# 类挂到 VContainer 自己的 PlayerLoop。
|
||
- 可用接口与大致时机：
|
||
- `IInitializable` / `IPostInitializable`
|
||
- `IStartable` / `IAsyncStartable` / `IPostStartable`
|
||
- `IFixedTickable` / `IPostFixedTickable`
|
||
- `ITickable` / `IPostTickable`
|
||
- `ILateTickable` / `IPostLateTickable`
|
||
- `IDisposable`（随容器释放）
|
||
- 未捕获异常可用 `RegisterEntryPointExceptionHandler` 自定义处理。
|
||
|
||
## 性能与优化
|
||
|
||
- 官方定位：相对 Zenject 在 Resolve 路径上更快、GC 更低。
|
||
- 默认使用反射；可启用 Source Generator 提升运行时性能。
|
||
- Source Generator 要求 Unity 2021.3+；从 v1.13.0 起基于 Roslyn Source Generator。
|
||
|
||
## 我的落地建议（Unity 项目）
|
||
|
||
- 把 `LifetimeScope` 当成“模块边界”，按场景/系统拆分父子 Scope。
|
||
- 业务逻辑放纯 C#，`MonoBehaviour` 尽量薄，只做视图与桥接。
|
||
- 高频路径优先构造函数注入，减少运行期反射与临时分配。
|
||
- 先统一生命周期约定（Singleton/Scoped/Transient 选择标准），再大规模迁移。
|
||
|
||
## 参考页面
|
||
|
||
- About: https://vcontainer.hadashikick.jp/
|
||
- Installation: https://vcontainer.hadashikick.jp/getting-started/installation
|
||
- Hello World: https://vcontainer.hadashikick.jp/getting-started/hello-world
|
||
- Register Plain C# Type: https://vcontainer.hadashikick.jp/registering/register-type
|
||
- Lifetime Overview: https://vcontainer.hadashikick.jp/scoping/lifetime-overview
|
||
- Plain C# Entry point: https://vcontainer.hadashikick.jp/integrations/entrypoint
|
||
- Source Generator: https://vcontainer.hadashikick.jp/optimization/source-generator
|