VContainer Installer扩展（DI）

约 1744 字大约 6 分钟

2026-03-14

重要

请先确保你对Dependency Injection（DI）和 VContainer的基本工作原理有一定认知；如果没有，请先硅基生物，以及搭配VContainer文档食用

本文默认你已经了解以下基础概念：

DI 的目的（解耦、可替换、可测试）
VContainer 的基础用法（LifetimeScope、IContainerBuilder、Lifetime）

本文重点不是重复 DI 教程，而是回答三个问题：

这个项目在 VContainer 之上额外封装了什么。
这些封装分别解决了什么协作问题。
在 Cofcity 里如何实际使用与排错。

2. 封装总览：在原生 VContainer 之上加了哪些层

Ruka/Cofcity 的扩展核心在于把“安装逻辑”拆成可组合、可过滤、可自动收集的模块。

2.1 类型关系（简化）

InstallerBase (ScriptableObject)
  ├─ CompositeInstaller                  // 资产级聚合器
  ├─ AutoGroupCollectionInstaller        // 自动分组收集执行器
  └─ 各业务 InstallerAsset（如 StateMachineInstaller 等）

IInstallerFilter
  ├─ IProjectInstaller
  └─ ISceneInstaller

NestedLifetimeScope
  └─ CompositeLifetimeScope              // 场景/预制体上的 Scope 聚合器

2.2 各模块的职责

LifetimeScope扩展

CompositeLifetimeScope：把组合安装能力直接挂到场景/Prefab 上（继承 NestedLifetimeScope）。
NestedLifetimeScope：自动找父 Scope，降低手工拖拽 parent 的维护成本。

资产型Installer

InstallerBase：统一安装器资产基类，所有安装入口统一成 Install(IContainerBuilder builder)。
CompositeInstaller：把多个 InstallerBase 资产组合起来，并可按过滤接口筛选。

自动维护型Installer

FeatureInstallerAttribute + IFeatureInstaller：支持“纯 C# 安装器类”声明分组和顺序。
AutoGroupCollectionInstaller：把某个 Group 对应的 IFeatureInstaller 自动执行，不再手动维护长列表。（这个是要创建资产的Installer，相当于一个资产管一组FeatureInstaller）
InstallerManifestProcessor（Editor）：脚本重载或资产导入时，自动刷新分组清单。

3. 运行链路：项目里一次容器装配是怎么发生的

以 Cofcity 的项目级和关卡级为例：

场景中的 Scope 节点（如 ProjectContext、StageRootScope）挂 CompositeLifetimeScope。
CompositeLifetimeScope 根据 moduleInstallers 执行安装器资产。
其中某些是 CompositeInstaller 资产（例如 ProjectContextInstallers.asset、StageSceneInstallers.asset），继续展开子安装器。
子安装器里可包含 AutoGroupCollectionInstaller 资产（如 ProjectCoreGroupInstaller.asset、StageFeaturesGroupInstaller.asset）。
AutoGroupCollectionInstaller 执行 qualifiedTypes 中的 IFeatureInstaller 类型；这个列表由 Editor 自动回填并按 Order 排序。
最终所有注册汇总进当前 Scope 的 VContainer 容器。

4. 关键模块解读与使用方式

4.1 InstallerBase：统一安装入口

public abstract class InstallerBase : ScriptableObject, IInstaller
{
    public abstract void Install(IContainerBuilder builder);
}

使用建议：

需要暴露为可配置资产（可拖拽、可复用）时，用 InstallerBase 子类。
纯代码特性驱动、无需资产实例化时，用 IFeatureInstaller。

4.2 CompositeInstaller：资产列表聚合

适合把多个安装器资产打包成一个“安装包”。

特点：

moduleInstallers：组合列表。
filter：可选过滤器类型（常见为 IProjectInstaller/ISceneInstaller）。

典型用途：

ProjectContextInstallers.asset 里集中挂项目级模块。
StageSceneInstallers.asset 里集中挂关卡相关模块。

4.3 NestedLifetimeScope / CompositeLifetimeScope：Scope 侧的工程化封装

NestedLifetimeScope 解决两个常见问题：

父子 Scope 链接：autoParent 自动向上查找父 LifetimeScope。
构建时序：如果父容器还没准备好，会等待后再构建，减少初始化竞态。

CompositeLifetimeScope 在此基础上增加了“可配置安装器列表”，用于场景节点直接编排模块。

常用字段理解：

autoParent：推荐开启（窗口/子节点场景最常见）。
parentScope：仅在关闭 autoParent 时才生效。
autoInjectSelf：需要自注入当前物体时开启。
filter：限制可执行安装器类型。

4.4 FeatureInstaller + AutoGroupCollectionInstaller：自动分组收集

重要

底下这个会用的比较多

4.4.1 代码侧声明

[FeatureInstaller(InstallerGroupNames.ProjectCore, 100)]
public sealed class StaticDataProjectFinstaller : IFeatureInstaller
{
    public void Install(IContainerBuilder builder)
    {
        // 注册逻辑
    }
}