---
name: luban-config
description: Luban 配置表操作：生成代码、修改配置、校验数据。涉及配置表（Excel/XML）和 Luban 工具链的操作。触发关键词：配置表 config table、Luban 导出 export、Excel 数据、Root.xml、GenCode、LubanExportConfig、数值配置、新增配置表、配置校验。
version: "1.0"
updated: "2026-05-08"
---

# Luban 配置表操作

操作游戏配置表系统，基于 Luban 工具链。

## 前置知识

- **Luban 工具位置**: `Assets/PhxhSDK/Phxh/ThirdParty/Luban/`
- **导出配置**: `Assets/PhxhSDK/Editor/Settings/Luban_*.asset`（Client_CN/Client_EN/Server）
- **生成代码**: `Assets/Code/Scripts/GenCode/Luban/`（Luban 生成的 C# 代码）
- **配置表源文件**: 位于 NLDMisc 仓库（`../../../NLDMisc`），通常为 Excel 格式
- **NLDMisc 典型结构**: `NLDMisc/Data/` 下按功能模块分目录存放 Excel 文件
- **Editor 脚本**: `Assets/PhxhSDK/Phxh/ThirdParty/Luban/Editor/LubanExportConfig.cs`
- **Root.xml 定义**: 在 NLDMisc 仓库中，注册所有表的字段和类型定义

## 配置表导出配置说明

Luban 使用 `LubanExportConfig` (ScriptableObject) 管理导出参数：

- `which_dll`: 数据校验 DLL（Client&Server 共用）
- `define_xml`: Root.xml 定义文件
- `service`: 生成目标（server / client）
- `-t`: 生成类型参数
- `-c`: 其他命令行参数
- `before_gen` / `after_gen`: 生命周期回调脚本

配置文件路径模式:
```
Assets/PhxhSDK/Editor/Settings/Luban_Client_CN.asset   # 客户端中文
Assets/PhxhSDK/Editor/Settings/Luban_Client_EN.asset   # 客户端英文
Assets/PhxhSDK/Editor/Settings/Luban_Server.asset      # 服务端
```

## 不适用场景

- 只修改了游戏逻辑代码（不涉及配置表）→ 不需要走 Luban 流程
- 只查配置表字段结构 → 直接看 `Assets/Code/Scripts/GenCode/Luban/` 中的生成代码即可

## 工作流

### 1. 修改配置表

当需要修改游戏配置参数时：

1. **定位配置表**: 根据功能需求找到对应的 Excel/CSV 配置文件
2. **理解字段含义**: 查看 `Assets/Code/Scripts/GenCode/Luban/` 中生成的 C# 类了解字段结构
3. **修改数据**: 编辑配置表文件中的具体数值
4. **重新导出**: 提示用户在 Unity Editor 中执行 Luban 导出（菜单路径: `Luban/Export` 或 `Phxh/Luban/Export`）

### 2. 新增配置表

1. 在 `Root.xml` 中注册新表定义
2. 创建 Excel 源文件
3. 执行 Luban 导出生成 C# 代码
4. 验证生成的代码在 `Assets/Code/Scripts/GenCode/Luban/` 中

### 3. 配置校验

- 导出过程中 Luban 会自动根据 `which_dll` 指定的校验 DLL 进行数据校验
- 校验失败会在 Unity Console 输出错误信息
- 常见校验错误：字段类型不匹配、引用 ID 不存在、必填字段为空

## 生成代码规范

Luban 生成的代码位于 `Assets/Code/Scripts/GenCode/Luban/`：
- 每个配置表对应一个 C# 类
- 类名通常与配置表名一致
- 包含字段属性、索引查找方法、验证逻辑
- **不要手动修改生成代码**（重新导出会覆盖）

## 安全规则

- 修改配置表前确认当前编辑的是正确的 target（Client/Server）
- 导出前备份重要配置数据
- 配置表变更通常涉及三仓（NLDClient + NLDMisc），需走 batch-git-ops 流程
- 多语言配置需同步更新 CN/EN 两个版本
- 新增字段需同步更新服务端和客户端的 Root.xml 定义