简介Excel转Lua工具是一款面向游戏开发与配置管理场景的辅助脚本主要解决Excel表格数据难以被Lua程序直接读取的问题适合使用Lua作为主要脚本语言的开发者及数据驱动型项目团队。资源包共4个文件包含1个xlsx示例表格、1个py转换脚本、1个bat批处理启动文件以及1份docx使用说明压缩包约159KB体积轻巧便于快速部署。其中Python脚本负责解析表格并生成Lua代码批处理文件简化运行流程示例表格与说明文档则帮助理解转换规则与导出结构。目前已有690人学习下载。通过该工具开发者可将角色属性、物品配置、地图信息等结构化数据批量转换为清晰可读的Lua表减少运行时对Excel库的依赖提升程序性能同时便于团队在开发阶段快速修改与调试数据把精力集中在业务逻辑实现上。1. 从一张配表翻车说起excel转lua工具到底装什么上周帮一个做模拟项目X的哥们排查问题他那边策划改完 Excel 配表程序跑起来数值全乱查了一晚上以为是逻辑 bug最后发现是 excel转lua 这一步根本没跑通——工具装是装了但 Python 版本不对openpyxl 读出来的合并单元格全是 None导出的 lua 表里字段直接错位。这种坑我见过太多次了excel转lua工具本身不复杂难的是环境依赖和版本匹配装不好就是给自己埋雷。这套环境适合两类人一类是刚接手项目配表流程的新人需要从零把 excel转lua 跑起来另一类是换机器或者升级 Python 之后发现老脚本跑不动得重新配一遍。核心就三件事Python 环境、Excel 解析库、lua 输出格式约定。下面按我实际装机的顺序把每一步拆开讲包括我踩过的版本坑和参数取舍。2. 环境准备Python 版本和依赖库怎么选2.1 Python 版本别追新3.8 到 3.10 最稳excel转lua 这类脚本工具底层依赖 openpyxl 或 xlrd 读表再拼字符串写 .lua 文件。Python 3.11 之后部分 C 扩展库的 wheel 包还没跟上尤其是 Windows 上装 lxml 容易卡在编译。我一般推荐 3.8 到 3.10 之间的版本3.9 用得最多兼容性最好。装 Python 本身没什么好说的官网下载安装包勾选 Add to PATH。装完验证python --version pip --version如果 pip 版本太老先升级python -m pip install --upgrade pip这里有个细节Windows 上如果同时装了多个 Python 版本python命令可能指向 3.11 而pip指向 3.9导致装库装错地方。用where python和where pip确认路径一致不一致就用python -m pip install显式指定。2.2 核心依赖openpyxl 和 xlrd 的分工读 Excel 有两个主流库分工不同库名支持格式适用场景安装命令openpyxl.xlsx新版 Excel支持读写pip install openpyxlxlrd.xls老版 Excel2.0 后只读pip install xlrd1.2.0pandas两者都行需要做数据清洗时pip install pandas我一般只装 openpyxl因为现在策划基本都用 .xlsx。但如果项目里有历史 .xls 文件xlrd 必须锁 1.2.0 版本2.0 之后它把 xls 支持砍了装最新版反而读不了老表。pip install openpyxl3.1.2 pip install xlrd1.2.0openpyxl 3.1.x 对合并单元格的处理比 3.0 稳定读merged_cells范围时不会漏掉边界。装完验证import openpyxl wb openpyxl.load_workbook(test.xlsx) print(wb.sheetnames)能打印出 sheet 名就说明环境通了。2.3 项目目录结构别把脚本和配表混在一起我习惯把 excel转lua 工具单独放一个目录和策划的 Excel 源文件分开excel2lua/ ├── tool/ │ ├── convert.py # 主转换脚本 │ └── config.json # 字段映射配置 ├── excel/ # 策划配表目录 │ ├── item.xlsx │ └── monster.xlsx └── output/ # 生成的 lua 文件 ├── item.lua └── monster.lua这样做的好处是转换脚本可以复用换项目只改 config.json 里的字段映射不用动代码。config.json 里一般配这几项{ excel_dir: ../excel, output_dir: ../output, sheet_prefix: Sheet, key_row: 1, type_row: 2, data_start_row: 4, lua_table_name: config }key_row是字段名所在行type_row是类型行data_start_row是数据起始行。不同项目策划的表头行数不一样这三个参数必须对着实际 Excel 改改错了导出的 lua 表字段全是乱的。3. 安装与配置转换脚本的落地步骤3.1 获取脚本并安装依赖excel转lua 工具网上有现成的开源脚本也可以自己写。我一般用自己维护的一套核心逻辑就百来行。拿到脚本后先看 requirements.txtcd excel2lua/tool pip install -r requirements.txt如果没有 requirements.txt手动装pip install openpyxl xlrd1.2.0这里注意如果项目里用了argparse做命令行参数Python 自带不用装如果用了pyyaml读 yaml 配置需要额外装pip install pyyaml装完用pip list确认版本重点看 openpyxl 是不是 3.1.xxlrd 是不是 1.2.0。3.2 配置字段映射类型转换是重头戏Excel 里的单元格读出来默认是 Python 的 str、int、float 或 datetime写 lua 表时需要转成 lua 能识别的格式。我一般在 config.json 里配类型映射{ type_map: { int: number, float: number, string: string, bool: boolean, array: table }, default_values: { number: 0, string: , boolean: false, table: {} } }转换脚本里对应处理def convert_value(cell_value, cell_type): if cell_type int: return int(cell_value) if cell_value else 0 elif cell_type float: return float(cell_value) if cell_value else 0.0 elif cell_type string: return str(cell_value) if cell_value else elif cell_type bool: return true if cell_value else false elif cell_type array: # 数组用逗号分隔转成 lua table items str(cell_value).split(,) return { ,.join(items) } return cell_valuecell_type从 Excel 的类型行读取cell_value是数据行的值。空单元格必须给默认值否则 lua 表里会出现 nil运行时取字段直接报错。数组类型我一般约定用逗号分隔转成{1,2,3}这种 lua table 格式。3.3 处理合并单元格读之前先展开策划的表经常有合并单元格比如一个字段跨两列或者表头合并。openpyxl 读合并单元格时只有左上角那个格有值其他格是 None。我一般先展开def unmerge_cells(ws): merged_ranges list(ws.merged_cells.ranges) for merged_range in merged_ranges: min_col, min_row, max_col, max_row merged_range.bounds top_left_value ws.cell(rowmin_row, columnmin_col).value ws.unmerge_cells(str(merged_range)) for row in range(min_row, max_row 1): for col in range(min_col, max_col 1): ws.cell(rowrow, columncol).value top_left_value return wsmerged_range.bounds返回合并区域的左上角和右下角坐标先把值取出来取消合并再把值填回每个格。这样后续按行读数据就不会漏字段。注意这个操作会修改 workbook 对象如果还要保留原文件先 copy 一份。3.4 生成 lua 文件格式和编码别搞错写 lua 文件时编码统一用 utf-8换行用\n别用 Windows 的\r\n否则在某些 lua 解析器里会多出空白字符。我一般这样写def write_lua_file(data, output_path, table_name): with open(output_path, w, encodingutf-8, newline\n) as f: f.write(flocal {table_name} {{\n) for row in data: f.write( {) for k, v in row.items(): f.write(f{k} {v}, ) f.write(},\n) f.write(}\n) f.write(freturn {table_name}\n)newline\n强制用 Unix 换行encodingutf-8保证中文不乱码。最后加return语句方便 lua 里require加载。如果项目用的是config这种全局表名把table_name改成对应名字就行。4. 避坑与排查excel转lua 最常见的五个翻车点4.1 现象导出的 lua 表字段顺序和 Excel 不一致原因Python 3.7 之前 dict 不保证插入顺序openpyxl 读出来的列顺序可能和 Excel 视觉顺序不同。解决用collections.OrderedDict或者升级到 Python 3.7并且在读表时按列索引显式排序from collections import OrderedDict row_data OrderedDict() for col in sorted(ws.iter_cols(min_rowdata_start_row, max_rowws.max_row)): # 按列索引处理 pass4.2 现象中文变成乱码或者问号原因Excel 文件本身是 GBK 编码或者 Python 默认编码不是 utf-8。解决读文件时显式指定编码写文件时也用 utf-8wb openpyxl.load_workbook(item.xlsx, read_onlyTrue) # 写的时候 with open(item.lua, w, encodingutf-8) as f: f.write(content)如果 Excel 是 .xls 老格式xlrd 读出来是 unicode写的时候统一转 utf-8 就行。4.3 现象数字被读成浮点数lua 里显示 1.0 而不是 1原因Excel 里数字单元格默认是 floatopenpyxl 读出来就是 1.0。解决在类型转换时判断是不是整数def to_number(value): if isinstance(value, float) and value.is_integer(): return int(value) return value这样 1.0 会转成 1lua 表里就是整数。4.4 现象空行导致 lua 表里多出空记录原因Excel 末尾有空白行ws.max_row把空行也算进去了。解决读数据时跳过全空的行for row in ws.iter_rows(min_rowdata_start_row, max_rowws.max_row): if all(cell.value is None for cell in row): continue # 处理非空行4.5 现象pip 装 openpyxl 报错 Permission denied原因Windows 上没管理员权限或者 Python 装在系统目录。解决用--user参数装到用户目录pip install --user openpyxl3.1.2或者直接用虚拟环境python -m venv venv venv\Scripts\activate pip install openpyxl3.1.2虚拟环境最干净换项目不用重新配。5. 验证跑通用一张测试表走完整流程装完之后别急着上正式配表先拿一张测试 Excel 走一遍。我一般建一个test.xlsx内容如下idnamehpattackskills1小怪10010.51,22大怪50025.03,4,5表头行是字段名第二行是类型int, string, int, float, array第三行空着第四行开始是数据。然后跑转换脚本python convert.py --config config.json --excel test.xlsx --output test.lua跑完检查output/test.lualocal config { {id 1, name 小怪, hp 100, attack 10.5, skills {1,2}, }, {id 2, name 大怪, hp 500, attack 25, skills {3,4,5}, }, } return config重点看几个地方attack字段 10.5 保留小数25.0 转成了 25skills字段正确转成了 lua table中文没有乱码字段顺序和 Excel 一致。如果都对了再用 lua 解释器加载验证lua -e local t require(test); print(t[1].name, t[2].hp)输出小怪 500就说明整条链路通了。如果报module test not found检查 lua 的package.path有没有包含 output 目录或者直接用dofile(output/test.lua)加载。从那以后我每次换机器或者升级 Python都强制先跑一遍这张测试表确认 openpyxl 版本、编码、合并单元格处理都没问题再动正式配表。这个习惯帮我省了至少三次通宵排查的时间。希望帮到你。本文还有配套的精品资源点击获取