Excel2Json Converter

一个轻量级、灵活的 Excel 到 JSON 转换工具。支持命令行操作，适用于游戏开发配置表导出、数据转换等场景。

功能特性

• 支持 Array（数组列表）和 Object（键值对对象）两种数据结构导出。
• 支持命令行参数指定输入/输出目录。
• 支持多种数据类型自动转换（Number, String, Boolean, JSON/Array）。
• 支持注释列/行（以 # 开头），灵活控制数据导出。
• 跨平台支持（Windows, macOS, Linux）。

安装

全局安装（推荐）

npm install -g @boume/excel2json-cli

使用指南

安装后，你可以直接在终端使用 excel2json 命令。

命令行参数

Usage: excel2json [options]

Options:
  -i, --input <dir>   指定输入 Excel 文件夹路径 (默认: 当前工作目录)
  -o, --output <dir>  指定输出 JSON 文件夹路径 (默认: ./json)
  -h, --help          显示帮助信息

示例

1. 基本用法： 在包含 Excel 文件的目录下直接运行：

   excel2json

   这将读取当前目录下的 .xlsx 文件，并在当前目录下创建 json 文件夹输出结果。

2. 指定输入输出目录：

   excel2json -i ./excels -o ./assets/resources/json

示例文件

本项目包含一个示例文件 example/GameConfig.xlsx，你可以直接运行以下命令查看转换效果：

excel2json -i example -o example/json

1. 数组类型 (Array)

Sheet 名称: Array.装备配置表

Excel 内容预览:

| (A列) | ID | 名称 | 类型 | 图标 | | :--- | :--- | :--- | :--- | :--- | | (Key) | id | name | type | icon | | (Type) | string | string | string | string | | (备注) | | | | | | | 1 | 青龙偃月刀 | p1 | e1-p1 | | | 2 | 青龙盔 | p2 | e1-p2 |

生成的 JSON (装备配置表.json):

[
  { "id": "1", "name": "青龙偃月刀", "type": "p1", "icon": "e1-p1" },
  { "id": "2", "name": "青龙盔", "type": "p2", "icon": "e1-p2" }
]

2. 对象类型 (Object)

Sheet 名称: Object.英雄属性

Excel 内容预览:

| (A列) | (B列) | (C列) | (D列) | | :--- | :--- | :--- | :--- | | 中文名 | Key | Type | Value | | 生命 | hp | number | 1000 | | 攻击 | atk | number | 100 | | 防御 | def | number | 50 | | 速度 | speed | number | 1 |

生成的 JSON (英雄属性.json):

{
  "hp": 1000,
  "atk": 100,
  "def": 50,
  "speed": 1
}

配置表规范

为了正确导出 JSON，Excel 文件需遵循以下规范。

1. 工作表 (Sheet) 命名

Sheet 名称决定了导出数据的结构类型。格式为：类型.表名

| Sheet 名称 | 导出结构 | 说明 | | :--- | :--- | :--- | | Array.User | [...] | 导出为对象数组。文件名将为 User.json | | Object.Config | {...} | 导出为单个对象。文件名将为 Config.json |

2. Array 类型表结构

适用于列表型数据（如：物品表、怪物表）。

| 行/列 | 说明 | | :--- | :--- | | 第 1 列 (A) | 侧边注释，完全忽略，不参与解析。 | | 第 1 行 | 中文名。如果以 # 开头，则忽略该列。 | | 第 2 行 | Key (变量名)，必填。 | | 第 3 行 | Type (数据类型)。 | | 第 4 行 | 备注，忽略。 | | 第 5 行+ | 数据内容。 |

3. Object 类型表结构

适用于全局配置、单例数据。

| 行/列 | 说明 | | :--- | :--- | | 第 1 行 | 表头，完全忽略。 | | 第 1 列 (A) | 中文名。如果以 # 开头，则忽略该行。 | | 第 2 列 (B) | Key (变量名)，必填。 | | 第 3 列 (C) | Type (数据类型)。 | | 第 4 列 (D) | Value (数据值)。 | | 第 5 列+ | 备注，忽略。 |

4. 支持的数据类型

在类型行/列中填写的类型：

• number / int: 数字
• string: 字符串
• bool / boolean: 布尔值 (1/true 为真)
• json / array: JSON 对象或数组 (例如 [1, 2] 或 {"a": 1})

License

ISC