# 手动测试 12 · 区域相机系统

> **测试类型**：Unity Editor 手动测试（Play Mode）  
> **覆盖模块**：`CameraArea`、`CameraTriggerZone`、`CameraStateController`、`CinemachineConfiner2D`、`CameraBlendProfileSO`  
> **前置文档**：`Phase1_Verification_Guide.md` §1（验证前准备）

---

## 快速工具

| 工具 | 用途 | 菜单路径 |
|------|------|----------|
| **Camera Area Setup（窗口）** | 扫描场景中所有 CameraArea/TriggerZone/Controller，显示绑定状态，提供一键修复 | `BaseGames → Camera → Camera Area Setup` |
| **Place Camera Area** | 生成 CameraArea 节点（含 PolygonCollider2D 限位边界） | `BaseGames → Scene → Place → Camera Area` |
| **Place Camera Trigger Zone** | 生成 CameraTriggerZone + BoxCollider2D Trigger | `BaseGames → Scene → Place → Camera Trigger Zone` |

**典型工作流**：
1. 在 Persistent 场景中放置两台全局虚拟相机（`VCamA` / `VCamB`），绑定到 `CameraStateController._vcamA/_vcamB`。
2. 在关卡场景中使用 **Place Camera Area** 为每个相机区域放置 `CameraArea` 数据节点（一个房间可放多个）。
3. 选中 `CameraArea`，在 Scene 视图中拖拽**黄色可视区域**的边 Handle 调整可见范围，然后点击 Inspector 底部 **「从可视区域更新限位区域（透视）」** 自动换算限位多边形。
4. 使用 **Place Camera Trigger Zone** 在区域入口放置触发器，并将目标 `CameraArea` 拖入 `_targetArea`。
5. 打开 **Camera Area Setup** 窗口，点击 **为全局 VCam 赋值 Follow 目标**（会自动在 Player 下创建或复用 `CameraFollowTarget` 子节点并绑定）。
6. 所有条目显示绿色 ● → 进入 Play Mode 验证。

---

## 目录

1. [系统架构说明](#1-系统架构说明)
2. [Persistent 场景配置（CameraStateController）](#2-persistent-场景配置cameraStatecontroller)
3. [关卡场景配置（CameraArea + CameraTriggerZone）](#3-关卡场景配置cameraarea--cameratriggerzone)
4. [ScriptableObject 资产说明](#4-scriptableobject-资产说明)
5. [Camera Area Setup 工具详解](#5-camera-area-setup-工具详解)
6. [验收测试用例](#6-验收测试用例)
7. [常见问题排查](#7-常见问题排查)

---

## 1. 系统架构说明

```
Persistent.unity
└── [Camera]
    └── CameraStateController          ExecutionOrder = -100
          组件: CameraStateController
          │     _vcamA   → VCamA（全局虚拟相机 A）
          │     _vcamB   → VCamB（全局虚拟相机 B）
          │     _lookSystem → CameraLookSystem 节点
          组件: CinemachineBrain        ← 实际渲染相机（随 Main Camera 放置）
          组件: CinemachineImpulseSource ← 屏幕抖动信号源
    ├── CameraLookSystem               ← 运行时由 SetFollowTarget() 赋值基准目标
    │     组件: CameraLookSystem        双轴窥视偏移 + 速度门控；输出 VirtualTarget
    ├── VCamA
    │     组件: CinemachineCamera       Follow = CameraLookSystem.VirtualTarget（运行时自动赋值）
    │     组件: CinemachinePositionComposer    Body 跟随组件；初始值与 CameraArea 默认值对齐
    │     组件: CinemachineConfiner2D   ← 由 CameraStateController 动态更新 BoundingShape2D
    │     组件: CameraAxisLockExtension       锁定 X 或 Y 轴（竖井 / 走廊场景）
    │     组件: CameraAsymmetricDampingExtension  非对称 Y 阻尼（下落快恢复，起跳慢追赶）
    │     组件: CameraAdaptiveLookaheadExtension   速度自适应 Lookahead（移动快 → 预见更多）
    └── VCamB
          组件: CinemachineCamera       Follow = CameraLookSystem.VirtualTarget（运行时自动赋值）
          组件: CinemachinePositionComposer    同 VCamA
          组件: CinemachineConfiner2D   ← 由 CameraStateController 动态更新 BoundingShape2D
          组件: CameraAxisLockExtension
          组件: CameraAsymmetricDampingExtension
          组件: CameraAdaptiveLookaheadExtension

Level_01.unity
├── [CameraAreas]
│   ├── CameraArea_A                   区域 A（可在同一房间内放置多个）
│   │   组件: CameraArea               _confinerCollider → PolygonCollider2D
│   │   │                             _visibleBounds（可视矩形）
│   │   │                             _blendProfile → CameraBlendProfileSO（可选）
│   │   │                             _dedicatedCamera（专有 VCam，可选，priority > 全局）
│   │   └── PolygonCollider2D         定义该区域的相机限位边界
│   │
│   └── CameraArea_B                   区域 B
│       ...（同上）
│
└── [Triggers]
    ├── CameraTriggerZone_AB           区域 A→B 入口
    │   组件: CameraTriggerZone         _targetArea = CameraArea_B
    │   组件: BoxCollider2D             isTrigger = true
    └── CameraTriggerZone_BA           区域 B→A 入口
        组件: CameraTriggerZone         _targetArea = CameraArea_A
        组件: BoxCollider2D             isTrigger = true
```

**核心流程**：
1. 玩家进入 `CameraTriggerZone` → `OnTriggerEnter2D` 调用 `ICameraService.SwitchArea(targetArea)`
2. `CameraStateController.SwitchArea` → 应用 `BlendProfile` 到 `CinemachineBrain.DefaultBlend`
   - **无专有 VCam**：配置非活跃全局 VCam 的 `CinemachineConfiner2D.BoundingShape2D` → 提升其优先级至 10 → 降低旧 VCam 优先级至 0（ping-pong），Cinemachine Brain 自动触发混合过渡
   - **有专有 VCam**：提升 `_dedicatedCamera` 优先级至 `_dedicatedPriority`（默认 20），高于全局 VCam，Cinemachine 自动切换

---

## 2. Persistent 场景配置（CameraStateController）

### 2.1 组件放置

在 Persistent 场景的 `[Camera]` 下建立以下节点结构：

| GameObject | 挂载组件 | 说明 |
|-----------|---------|------|
| `[CameraController]` | `CameraStateController`、`CinemachineBrain`、`CinemachineImpulseSource` | ExecutionOrder = -100 |
| `CameraLookSystem` | `CameraLookSystem` | 双轴窥视偏移（垂直+水平）+ 速度门控；输出 `VirtualTarget` 供 VCam 跟随；拖入 `CameraStateController._lookSystem` |
| `VCamA` | `CinemachineCamera`、**`CinemachinePositionComposer`**、`CinemachineConfiner2D`、`CameraAxisLockExtension`、`CameraAsymmetricDampingExtension`、`CameraAdaptiveLookaheadExtension` | 全局虚拟相机 A；**PositionComposer 是 Body 组件，必须存在**；拖入 `CameraStateController._vcamA` |
| `VCamB` | `CinemachineCamera`、**`CinemachinePositionComposer`**、`CinemachineConfiner2D`、`CameraAxisLockExtension`、`CameraAsymmetricDampingExtension`、`CameraAdaptiveLookaheadExtension` | 全局虚拟相机 B；同 VCamA；拖入 `CameraStateController._vcamB` |

> **注意**：`CinemachineBrain` 须挂在附有 `Camera` 组件（Main Camera）的 GameObject 上，
> 否则 Cinemachine 无法驱动视口渲染。两台全局 VCam 初始优先级均为 0，由 `CameraStateController` 在运行时动态管理。

### 2.2 字段绑定清单

打开 **Camera Area Setup** 窗口（`BaseGames → Camera → Camera Area Setup`），
在 **CameraStateController** 区域确认以下项目全为绿色 ●：

| 字段 | 期望状态 |
|------|---------|
| `_vcamA` (CinemachineCamera) | ● 已绑定 |
| `_vcamB` (CinemachineCamera) | ● 已绑定 |
| `_brain` (CinemachineBrain) | ● 已绑定 |
| `_lookSystem` (CameraLookSystem) | ● 已绑定 |
| `_impulseSource` (CinemachineImpulseSource) | ◌ 可选；用于屏幕抖动 |
| `_defaultBlendProfile` (CameraBlendProfileSO) | ◌ 可选；未设置则无混合过渡 |

---

## 3. 关卡场景配置（CameraArea + CameraTriggerZone）

### 3.1 添加 CameraArea

**方式 A：使用快速放置工具**（推荐）

1. 菜单 `BaseGames → Scene → Place → Camera Area`
2. 工具自动创建以下节点结构：
   ```
   CameraArea
   ├── CameraArea（组件，_confinerCollider 已绑定）
   └── PolygonCollider2D（默认矩形 24×12，isTrigger = true，定义限位区域）
   ```
3. 打开 **Camera Area Setup** 窗口，点击 **为全局 VCam 赋值 Follow 目标**
   （工具会自动在 Player 下查找或创建 `CameraFollowTarget` 子节点，绑定到两台全局 VCam）。
4. 手动调整子节点 `PolygonCollider2D` 顶点定义限位范围。

**方式 B：手动创建**

1. 新建空 GameObject，命名如 `CameraArea_A`
2. 挂载 `CameraArea`（BaseGames.Camera）
3. 在同一 GameObject 或子对象上创建 `PolygonCollider2D`
4. 将 `PolygonCollider2D` 拖入 `CameraArea._confinerCollider`
5. （可选）如需专有相机参数，新建独立 VCam GameObject，挂载 `CinemachineCamera`，拖入 `CameraArea._dedicatedCamera`

> **一个房间可放置多个 `CameraArea`**，如大厅区域与 Boss 区域分别使用不同的限位和混合配置。

### 3.2 调整限位区域（PolygonCollider2D）

`CameraArea` 上（或子节点）的 `PolygonCollider2D` 定义了相机在该区域内的移动边界。

- **编辑顶点**：选中 `CameraArea` 节点 → Inspector 中 `PolygonCollider2D` → 点击 **Edit Collider** 图标，在 Scene 视图拖动顶点
- **自动修复**：打开 **Camera Area Setup** 窗口，对应条目点击 **修复：绑定子节点 PolygonCollider2D**

> **最佳实践**：限位区域应比实际可见范围大一格以上（约 1 unit），避免相机卡在边缘。

### 3.3 添加 CameraTriggerZone

**使用快速放置工具**（推荐）

1. 菜单 `BaseGames → Scene → Place → Camera Trigger Zone`
2. 工具生成：
   ```
   CameraTriggerZone
   ├── CameraTriggerZone（组件，_playerTag = "Player"）
   └── BoxCollider2D（isTrigger = true，默认 2×2）
   ```
3. 在 Inspector 中将目标 `CameraArea` 拖入 `CameraTriggerZone._targetArea`
4. 调整 `BoxCollider2D` 大小至覆盖整个区域过渡走廊宽度（通常 2×3 或 2×4）

**典型布局**：

```
[区域 A]  ‖  [走廊]  ‖  [区域 B]
            ←← TriggerZone_A→B (_targetArea = CameraArea_B)
            TriggerZone_B→A (_targetArea = CameraArea_A) →→
```

> 双向过渡需要两个 TriggerZone 分别放置在走廊两端，各自指向对应区域的 `CameraArea`。

### 3.4 全局 VCam Follow 绑定

Persistent 场景中两台全局 VCam 的 `CinemachineCamera.Follow` **不直接指向 Player**，
而是指向 `CameraLookSystem` 组件在运行时生成的 **`[CameraLookTarget]` 虚拟目标节点**。  
该节点由 `CameraStateController.SetFollowTarget(Transform)` 在玩家注册时自动创建并赋值，
其世界位置 = Player 基准目标位置 + 当前窥视偏移（`CameraLookSystem` 的双轴输出）。

> **不要在 Inspector 中手动把 VCam.Follow 拖到 Player 本身或 Player/CameraFollowTarget。**  
> `SetFollowTarget` 会在运行时覆盖，且直接指向 Player 会绕过窥视偏移计算。

**工具支持**：  
**Camera Area Setup** 窗口 → **为全局 VCam 赋值 Follow 目标** 按钮  
→ 该按钮仅用于调试回退（绕过 LookSystem，直指 Player/CameraFollowTarget）。  
正式流程请通过 `ICameraService.SetFollowTarget(playerTransform)` 注册，由系统自动处理。

---

### 3.5 编辑可视区域（透视相机）

`CameraArea` 支持在 Scene 视图中直接定义摄像机的最大可视范围，并自动换算为限位 `PolygonCollider2D` 的顶点坐标。

**Inspector 字段**：

| 字段 | 说明 |
|------|------|
| `_visibleBounds` | 摄像机应显示的最大可视矩形（世界坐标）；Scene 视图选中时显示为**黄色矩形** |
| `_cameraDepth` | 摄像机到场景平面（Z = 0）的垂直距离；留 `0` 则自动读取 `\|transform.position.z\|` |

**Scene 视图拖拽编辑**：

选中 `CameraArea` GameObject 后，Scene 视图出现：
- **黄色矩形**：可视区域（玩家在此区域内的最大可见范围）
- **蓝色多边形**：当前 `PolygonCollider2D` 限位边界（参考用）

矩形四条边各有一个滑动 Handle，拖拽即可调整：
- 左 / 右边 Handle：沿 X 轴滑动
- 上 / 下边 Handle：沿 Y 轴滑动

**同步到限位区域**：

调整好可视区域后，在 Inspector 底部点击 **「从可视区域更新限位区域（透视）」**，工具根据以下公式换算限位多边形：

```
halfH   = depth × tan(vFOV / 2)
halfW   = halfH × aspectRatio
confiner = visibleBounds 向内收缩 (halfW, halfH)
```

> **含义**：相机视口边缘恰好与可视区域边框对齐。若区域小于单屏（inset 后为负），限位收缩为中心点，相机固定居中。

Inspector 参数预览区实时显示 FOV（来源：专有 VCam → 全局 VCamA → Camera.main → 60°）、深度、视口半宽 / 半高的计算值。

### 3.6 专有 VCam（特殊区域）

需要独特相机参数（如 Boss 区域特写 FOV）的区域，可在 `CameraArea._dedicatedCamera` 中指定一台独立的 `CinemachineCamera`：

1. 在关卡场景中新建空 GameObject，挂载 `CinemachineCamera`（设置好 Lens、Follow、Noise 等参数）
2. 将其拖入该 `CameraArea._dedicatedCamera`
3. `_dedicatedPriority`（默认 20）须高于全局 VCam 的激活优先级（10）

进入该区域时，`CameraStateController` 自动提升专有 VCam 优先级，Cinemachine 混合切换；离开时优先级归零，全局 VCam 重新接管。

---

## 4. ScriptableObject 资产说明

### 4.1 CameraBlendProfileSO

**创建路径**：`Assets → Create → BaseGames → Camera → BlendProfile`

| 字段 | 说明 | 典型值 |
|------|------|--------|
| `Style` | 混合曲线类型（EaseInOut / Linear / Cut / Custom） | `EaseInOut` |
| `BlendTime` | 混合持续时间（秒） | `0.5` |
| `CustomCurve` | 仅 `Style = Custom` 时使用 | — |

**使用**：
- 全局默认：拖入 `CameraStateController._defaultBlendProfile`
- 单独区域：拖入对应 `CameraArea._blendProfile`（覆盖全局默认）

### 4.2 CameraConfigSO

> ⚠ **Legacy / 已废弃**：`CameraConfigSO` 是早期相机系统的配置资产，现已不再被 `CameraStateController` 读取或应用。  
> 当前架构直接通过 `CameraArea` 字段（`ScreenPosition`、`DeadZoneSize`、`LookaheadTime`、`DampingDown`、`DampingUp` 等）在 `ConfigureSlot` 时写入 Cinemachine 组件，无需此 SO。  
> 若项目中仍存在 `CameraConfigSO` 资产，可安全忽略或删除。

~~**创建路径**：`Assets → Create → BaseGames → Camera → CameraConfig`~~

| 字段 | 说明 | 典型值 |
|------|------|--------|
| `FollowDamping` | ~~跟随阻尼~~ | — |
| `LookAheadTime` | ~~朝向预见时间~~ | — |
| `DeadZoneSize` | ~~死区尺寸~~ | — |
| `SoftZoneSize` | ~~软区尺寸~~ | — |
| `LookDownOffset` | ~~俯视偏移~~ | — |
| `LookUpOffset` | ~~仰视偏移~~ | — |
| `DefaultImpulseStrength` | ~~默认震屏强度~~ | — |


> `CameraConfigSO` 的配置值须由运行时的 `CameraStateController` 或相机系统读取并写入 Cinemachine 组件，具体写入逻辑取决于 `CameraStateController.ApplyConfig()` 的实现（如有扩展）。

---

## 5. Camera Area Setup 工具详解

菜单：`BaseGames → Camera → Camera Area Setup`

### 5.1 界面区域说明

**工具栏**
- `↻ 刷新`：手动重新扫描当前已加载场景
- `Place Camera Area`：快捷调用 `BaseGames → Scene → Place → Camera Area`
- `Place Trigger Zone`：快捷调用 `BaseGames → Scene → Place → Camera Trigger Zone`

**CameraStateController 区域**  
显示控制器组件绑定状态。若显示"未找到"提示，说明 Persistent 场景未加载（属正常）。

| 图标 | 含义 |
|------|------|
| `●`（绿） | 项目已正确配置 |
| `✗`（红） | 缺失必填项 |
| `◌`（黄） | 可选项未设置 |

检查项：`_vcamA`、`_vcamB`（必填）、`_brain`（必填）、`_lookSystem`（必填）、`_impulseSource`（可选）、`_defaultBlendProfile`（可选）

底部按钮：**为全局 VCam 赋值 Follow 目标** → 查找 Player/CameraFollowTarget 并写入两台 VCam 的 Follow 字段。

**Camera Areas 区域**  
为每个 `CameraArea` 显示一行，检查项：

| 字段 | 状态 |
|------|------|
| `_confinerCollider` (PolygonCollider2D) | 必填 |
| `_dedicatedCamera`（专有 VCam） | 可选 |
| `_blendProfile` | 可选 |

每行可点击 **修复：绑定子节点 PolygonCollider2D** 自动修复 `_confinerCollider` 未绑定的情况。

**Camera Trigger Zones 区域**  
列出所有 `CameraTriggerZone`，高亮显示 `_targetArea` 未绑定的项目（红色 ✗）。

### 5.2 典型使用流程

```
1. 打开窗口 BaseGames → Camera → Camera Area Setup
2. （仅首次）加载 Persistent 场景，确认 _vcamA/_vcamB/_brain 全绿
3. 在关卡场景中使用 Place Camera Area × N（一个房间可放多个）
4. 选中每个 CameraArea，在 Scene 视图拖拽黄色可视区域边 Handle，点击 [从可视区域更新限位区域（透视）]
5. 点击 [为全局 VCam 赋值 Follow 目标]（自动创建 Player/CameraFollowTarget 并绑定）
6. 使用 Place Trigger Zone 添加 N 个触发器，手动绑定 _targetArea
7. 所有条目绿色 ● → 进入 Play Mode 验证
```

---

## 6. 验收测试用例

### 测试前检查清单

| # | 检查项 | 操作 |
|---|--------|------|
| 1 | Console 无红色 Error | `Window → General → Console` |
| 2 | **Camera Area Setup** 窗口所有必填项为绿色 ● | `BaseGames → Camera → Camera Area Setup` |
| 3 | Player 已在场景中（tag = Player） | Hierarchy |
| 4 | Physics2D Layer 矩阵已配置 | `BaseGames → Tools → Validate Physics2D Layer Matrix` |

---

### MT-CAM-01：全局 VCam 正常跟随

**目的**：验证全局 VCam 激活后 `CinemachineCamera` 跟随玩家移动。

**步骤：**

1. Persistent 场景中放置 VCamA/VCamB，`Follow = Player/CameraFollowTarget`
2. 关卡场景中放置一个 `CameraArea`，通过 `CameraTriggerZone` 或 `RoomController` 触发 `SwitchArea`
3. 按 **Play**，在 Scene 视图和 Game 视图同时观察
4. 用 WASD/方向键移动 Player

**预期结果：**

| 检查点 | 期望 | ✓ |
|--------|------|---|
| Game 视图相机跟随 Player 移动 | 玩家靠近边缘时相机平滑跟进 | ☐ |
| 相机不会越出 CameraArea 的限位范围 | 玩家走到边角时相机贴边停止 | ☐ |
| 无跳变（平滑）跟随 | 无抖动、跳帧 | ☐ |

---

### MT-CAM-02：区域相机切换（CameraTriggerZone）

**目的**：验证玩家穿越触发器后全局 VCam ping-pong 平滑过渡到目标区域。

**步骤：**

1. 场景中放置两个 `CameraArea`（A、B），各有独立 `PolygonCollider2D` 限位
2. 在两区域之间放置两个 `CameraTriggerZone`（各自 `_targetArea` 互指）
3. 按 **Play**，引导 Player 穿越触发区进入区域 B

**预期结果：**

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 穿越触发器后 Game 视图开始混合过渡 | 相机平滑从 A 过渡到 B（非切割） | ☐ |
| 过渡时长约等于 `CameraBlendProfileSO.BlendTime` | 与 SO 设置一致（默认 0.5s） | ☐ |
| 过渡后相机限位在 CameraArea_B 的边界内 | 玩家无法把相机带出 B 的限位范围 | ☐ |
| 反向穿越触发器后相机切回 A | 同上，反向过渡 | ☐ |

---

### MT-CAM-03：CinemachineConfiner2D 边界限位

**目的**：验证 `CinemachineConfiner2D` 正确将相机限制在 `CameraArea` 限位范围内。

**步骤：**

1. 打开关卡场景，确认 `CameraArea._confinerCollider` 已绑定，且 `CameraStateController` 已调用 `SwitchArea`
2. 按 **Play**，将 Player 移动到房间的各个角落和边缘

**预期结果：**

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 相机在所有方向均不超出 `PolygonCollider2D` 多边形范围 | 无越界 | ☐ |
| 小房间（相机视口 > 房间）时相机居中，不晃动 | 稳定居中 | ☐ |

**常见失败原因**：
- `CameraArea._confinerCollider` 未绑定 → 打开 Camera Area Setup 点击修复
- PolygonCollider2D 顶点数量少于 3 → 确认 `_confinerCollider` 路径顶点完整

---

### MT-CAM-04：屏幕抖动（CinemachineImpulseSource）

**目的**：验证调用 `ICameraService.TriggerImpulse` 时 Game 视图画面抖动。

**步骤：**

1. 确认 `CameraStateController._impulseSource` 已绑定
2. 按 **Play**
3. 在 Console 执行（或通过游戏内事件触发）：
   ```csharp
   ServiceLocator.Get<ICameraService>().TriggerImpulse(0.5f);
   ```
   或让玩家受到一次伤害（若伤害系统已接入抖动调用）

**预期结果：**

| 检查点 | 期望 | ✓ |
|--------|------|---|
| Game 视图画面发生轻微抖动后恢复稳定 | 抖动时长约 0.2–0.4s，幅度可见 | ☐ |
| 无 Console 错误 | 无 NullReferenceException | ☐ |

---

### MT-CAM-05：初始场景无 CameraStateController 时安全降级

**目的**：验证场景中未加载 Persistent 场景时，`CameraTriggerZone` 不崩溃。

**步骤：**

1. 单独打开关卡场景（不加载 Persistent.unity）
2. 按 **Play**，移动 Player 穿越 `CameraTriggerZone`

**预期结果：**

| 检查点 | 期望 | ✓ |
|--------|------|---|
| 无 NullReferenceException | `ServiceLocator.GetOrDefault<ICameraService>()` 返回 null 时跳过 | ☐ |
| Console 可能有黄色 Warning（服务未注册） | 无红色 Error | ☐ |

---

### MT-CAM-06：多场景加载时相机状态正确恢复

**目的**：验证通过 `SceneLoader` 加载新场景时，`CameraStateController` 正确切换到新场景首个 `CameraArea`。

**步骤：**

1. 以 Persistent + Level_01 双场景启动
2. 按 **Play**，触发场景加载切换到 Level_02
3. Level_02 加载完成后观察相机

**预期结果：**

| 检查点 | 期望 | ✓ |
|--------|------|---|
| Level_02 的 `RoomController` 调用 `SwitchArea` 后相机切换正确 | 无黑屏、无旧场景相机残影 | ☐ |
| 旧场景 `CameraArea` 随场景卸载，全局 VCam 状态不受干扰 | 无相机混合错误 | ☐ |

> **注意**：全局 VCam 常驻 Persistent 场景，`CinemachineConfiner2D.BoundingShape2D` 在 `SwitchArea` 时动态更新，
> 旧场景卸载后引用会变为 null，须确保 `SwitchArea` 在新场景 `CameraArea` 可用后再调用。

---

## 7. 常见问题排查

| 现象 | 原因 | 解决 |
|------|------|------|
| Game 视图相机不动（黑屏或固定位置） | 全局 VCam `Follow` 未绑定 | `ICameraService.SetFollowTarget(player)` 注册玩家；或 Camera Area Setup → 为全局 VCam 赋值 Follow 目标 |
| 相机追赶卡顿/震颤 | `CinemachineConfiner2D.BoundingShape2D` 未绑定或碰撞体顶点有误 | 确认 `CameraArea._confinerCollider` 已绑定，PolygonCollider2D 顶点数 ≥ 3 |
| 进入区域后限位未更新（仍在旧区域限位内） | `CameraArea._confinerCollider` 为空，`ConfigureSlot` 跳过了更新 | 打开 Camera Area Setup 修复 `_confinerCollider` 绑定 |
| 场景中有多个 `CinemachineBrain` | Persistent 场景外又添加了含 Camera 组件的对象 | 仅 Main Camera 上保留一个 Brain |
| 过渡时画面闪切而非混合 | `CameraBlendProfileSO.BlendTime = 0` 或 Style = Cut | 检查 BlendProfile 并将 BlendTime 设置为 > 0 |
| `CameraStateController` 未找到（Console 错误） | Persistent 场景未加载 | 确认 Build Settings 中 Persistent.unity 第一位；开发测试用 `SceneManager.LoadScene("Persistent", Additive)` |
| 触发器无响应（玩家穿越后相机不切） | `CameraTriggerZone._targetArea` 未绑定，或 `_playerTag` 不匹配 | 检查 `_targetArea` 是否已拖入 `CameraArea`；确认 Player Tag = "Player" |
| `Camera Area Setup` 窗口列表为空 | 场景未保存或 DomainReload 后未刷新 | 点击窗口内 `↻ 刷新` 按钮 |
| 专有 VCam 不切换 | `_dedicatedPriority` ≤ 全局激活优先级（默认 10） | 将 `_dedicatedPriority` 设置为 > 10（默认 20 已满足） |
| Camera Area Setup 中 `_lookSystem` 红色 ✗ | `CameraStateController._lookSystem` 未绑定 | 将 Persistent 场景 `[Camera]/CameraLookSystem` 节点拖入该字段；或重新运行 SceneScaffoldTools |
| 按住方向键相机偏移不出现（窥视无效） | `CameraLookSystem._baseTarget` 未设置 | 确认 `ICameraService.SetFollowTarget(player)` 在玩家 Awake/Start 后调用 |
| 下落时相机跟随过慢（非对称阻尼异常） | `CameraAsymmetricDampingExtension` 未挂到 VCamA/VCamB，或 `DampingDown` 未被 `ConfigureSlot` 写入 | 确认两台 VCam 已挂载该扩展；检查 `CameraArea._dampingDown` > 0 |
| 高速移动时 Lookahead 不变化 | `CameraAdaptiveLookaheadExtension` 未挂到 VCamA/VCamB，或 `SetConfiguredMax` 未被调用 | 确认两台 VCam 已挂载该扩展；检查 `ConfigureSlot` 代码路径正常执行 |