做 Unity 项目时，策划给过来的配置表基本都是 Excel。每次都要手写实体类、写解析逻辑、处理类型转换、维护资源更新……这些重复劳动，现在可以交给 UnityExcelImporterX。

它能把 .xls、.xlsx 自动转换成 Unity 的 ScriptableObject 资源，并自动生成对应的 C# 实体类和容器类代码，真正做到“零代码导入 Excel”。

一、项目简介

UnityExcelImporterX 是一个 Unity Excel 数据导入工具，基于 unity-excel-importer 开发，并增加了一些新特性。

核心特性：

• 零代码生成：无需手动编写实体类脚本，自动生成完整代码
• 实时同步：Excel 修改后自动更新 Unity 资源
• 智能注释：支持注释行、注释列，灵活设置数据边界
• 类型丰富：支持基本类型、枚举、数组、字典、日期时间和自定义类型
• 多表支持：一次性导入 Excel 中的所有工作表
• 功能简单：无需配置，直接导入即可

二、环境要求

• Unity 版本：2021.3.45f1 或以上
• Excel 文件格式：.xls、.xlsx

三、安装方式

方式一：通过 .unitypackage 安装（推荐）

1. 访问 GitHub Releases 页面
2. 下载最新的 .unitypackage 文件
3. 双击文件，或在 Unity 中通过 Assets → Import Package → Custom Package 导入

方式二：通过 OpenUPM 安装

该包已发布至 OpenUPM。

安装前请确保项目已安装 NPOI 和 Newtonsoft.Json 依赖包：

openupm add net.nayaku.unity-excel-importer-x

方式三：通过 Package Manager 以 Git 依赖方式安装

同样需要先安装 NPOI 和 Newtonsoft.Json 依赖包。

1. 打开 Package Manager 窗口（菜单：Window | Package Manager）
2. 点击窗口左上角的 + 按钮，选择 Add package from git URL…
3. 输入以下 URL 并点击 Add：

https://github.com/nayaku/UnityExcelImporterX.git?path=Assets/UnityExcelImporterX

四、快速开始

步骤 1：创建 Excel 文件

按以下格式组织数据：

行号	内容说明	示例
第 1 行	字段名	id, name, price
第 2 行	C# 数据类型	int, string, float
第 3 行	注释	编号, 物品名, 售价
第 4 行及以后	实际数据	1, 物品名1, 99.5

将 Excel 文件放入 Unity 项目的 Assets 目录或其子目录中。

步骤 2：自动生成代码

在 Unity 中选中 Excel 文件，然后：

右键 → Create → ExcelAssetScript（或在顶部菜单选择 Assets → Create → ExcelAssetScript）

系统将自动生成实体类和容器类脚本，例如 MstItems.cs：

// 实体类 - 对应表格的每一行数据
[Serializable]
public class MstItemsEntity
{
    /// <summary>
    /// 编号
    /// </summary>
    public int id;           // 自动匹配 Excel 第 1 列
    /// <summary>
    /// 物品名
    /// </summary>
    public string name;      // 自动匹配 Excel 第 2 列
    /// <summary>
    /// 售价
    /// </summary>
    public float price;      // 自动匹配 Excel 第 3 列
}

// 容器类 - 存储所有表格数据
[ExcelAsset]
public class MstItems : ScriptableObject
{
    public List<MstItemsEntity> Entities;  // 所有行数据
}

⚠️ 重要提醒：当 Excel 表格结构发生变化时（如添加/删除列），需要重新执行此步骤生成最新代码。

步骤 3：自动导入数据

• 保存 Excel 文件（Ctrl+S）
• 回到 Unity，系统会自动检测变更并导入数据
• 在相同目录下会生成与 Excel 同名的 .asset 文件

如果没有自动生成，可以手动重新导入 Excel 文件来触发自动生成：右键点击 Excel 文件 → Reimport。

完成后，即可在 Unity Inspector 中直接查看和编辑导入的数据：

五、高级功能

1. 索引功能（主键字典）

在字段名后面追加 , key 可标记为主键，例如 id, key。支持多个主键。

生成的代码会包含一个 Dictionary，用于按主键快速查找数据：

[Serializable]
public class KeyExampleEntity
{
    public int id;
    /// <summary>
    /// name of item
    /// </summary>
    public string name;
    public float hp;
}

[ExcelAsset]
public class KeyExample : ScriptableObject, ISerializationCallbackReceiver
{
    public List<KeyExampleEntity> item = new();
    public Dictionary<(int id, string name), KeyExampleEntity> itemDict;

    public void OnBeforeSerialize()
    {
        // Implement any logic needed before serialization
    }

    public void OnAfterDeserialize()
    {
        // Implement any logic needed after deserialization
        itemDict = new();
        foreach (KeyExampleEntity item in item)
        {
            var key = (
                item.id,
                item.name
            );
            if (itemDict.ContainsKey(key))
            {
                Debug.LogError($"Duplicate key found in itemDict (script: KeyExample): {key}. Each key must be unique.");
                continue; // Skip adding this item to the dictionary
            }
            itemDict[key] = item;
        }
    }
}

* 如果出现重复主键，会输出错误日志并跳过该条数据。

2. 智能注释

行注释

在行的第一个单元格输入 #，整行将被忽略。

列注释

在列的第一行输入 #，整列将被忽略。

例如只导入 A、B 列，C 列被注释后：

[Serializable]
public class SummaryExampleEntity
{
    public int id; // 只导入 A、B 列，C 列被忽略
    /// <summary>
    /// name of item
    /// </summary>
    public string name;
}

[ExcelAsset]
public class SummaryExample : ScriptableObject
{
    public List<SummaryExampleEntity> item;
}

表注释

在工作表名字前输入 #，整个工作表将被忽略。

3. 数据边界

• 列边界：第一行出现空单元格时，右侧所有列将被忽略
• 行边界：第一列出现空单元格时，下方所有行将被忽略

4. 枚举类型

先创建一个 C# 枚举：

// 创建 ColorEnum.cs 文件
public enum ColorEnum
{
    RED,    // 红色
    GREEN,  // 绿色
    BLUE    // 蓝色
}

然后在 Excel 中直接填写枚举值，工具会自动匹配枚举类型：

[Serializable]
public class EnumExampleEntity
{
    public int id;
    /// <summary>
    /// 名字
    /// </summary>
    public string name;
    /// <summary>
    /// 颜色
    /// </summary>
    public ColorEnum color; // 自动匹配枚举类型
}

5. 复杂类型

支持数组类型、日期时间类型、字典类型和自定义类型。

使用数组类型时，可以省略方括号。

创建自定义类型 CustomType：

[Serializable]
public class CustomType
{
    public int x;
    public string s;
}

然后在 Excel 中直接填写对应数据即可。

6. 自定义资源路径

通过 AssetPath 参数控制生成的 .asset 文件位置：

[ExcelAsset(AssetPath = "Assets/Resources/MasterData")]
public class MstItems : ScriptableObject
{
    public List<MstItemsEntity> Entities;
}

7. 调试日志

开启导入日志，方便排查问题：

[ExcelAsset(LogOnImport = true)]  // 导入时输出详细日志
public class MstItems : ScriptableObject
{
    public List<MstItemsEntity> Entities;
}

8. 自定义文件关联

当 Excel 文件名与 ScriptableObject 类名不一致时使用：

// Excel 文件名为 "ItemData.xlsx"
// ScriptableObject 类名为 "MstItems"

[ExcelAsset(ExcelName = "ItemData")]  // 指定关联的 Excel 文件名
public class MstItems : ScriptableObject
{
    public List<MstItemsEntity> Entities;
}

9. 修改代码生成模板

代码生成模板位于：

Assets/UnityExcelImporterX/Editor/Templates/ExcelAssetScriptTemplete.cs.txt

可以根据项目规范自定义生成代码的风格。

六、常见问题

Q：Excel 修改后没有自动更新？

1. 确保 Excel 文件已保存
2. 在 Unity 中右键点击 Excel 文件 → Reimport
3. 检查控制台是否有错误信息

Q：修改表头后字段不匹配？

增删列、修改字段名或类型后，需要重新执行 Create → ExcelAssetScript，等待 Unity 编译完成后再导入。

Q：找不到生成的 .asset？

默认资源与 Excel 位于同一目录；如果设置了 AssetPath，请到指定目录查找。

项目地址

https://github.com/nayaku/UnityExcelImporterX

本项目采用 MIT 许可证，如果对你有帮助，欢迎给个 ⭐ Star 支持一下！