使用xlsx-template调用substitute方法报错，求问题排查方案

报错详情 #

TypeError: Cannot read properties of undefined (reading 'split')
at get (/app/node_modules/xlsx-template/lib/index.js:22:20)
at /app/node_modules/xlsx-template/lib/index.js:875:91
at Array.forEach ()
at Workbook.substituteTable (/app/node_modules/xlsx-template/lib/index.js:874:...)
at /app/node_modules/xlsx-template/lib/index.js:245:53
at Array.forEach ()
at /app/node_modules/xlsx-template/lib/index.js:232:54

核心原因 #

报错源于get函数中对一个undefined值调用了split方法，结合调用链判断，是处理表格模板替换时，某个预期为字符串的变量路径不存在或未正确传入。

排查方向及解决方法 #

• 模板占位符格式/路径错误：检查Excel模板中所有{{...}}占位符，确保内部变量路径完整合法。避免{{user.}}这类不完整路径，或{{}}空占位符，这类情况会导致库解析时得到undefined值，触发split报错。
• 替换数据结构不匹配：如果模板用了表格循环（如{{#tableList}}），需确保传入的tableList是数组，且数组内每个元素都包含模板中引用的所有字段。若tableList为undefined、非数组，或元素缺少对应属性，都会导致解析失败。
• 无效模板单元格：若某个单元格内的占位符格式损坏（比如只写了{{未闭合，或包含特殊字符未转义），库会错误解析变量路径，引发undefined问题。逐一检查模板中带占位符的单元格。
• 版本兼容性问题：旧版本的xlsx-template可能存在解析bug，尝试升级到最新稳定版，或降级到已知无此问题的版本测试。

验证步骤 #

1. 简化模板：只保留一个简单占位符（如{{test}}），传入{test: 'demo'}调用substitute，确认基础功能正常。
2. 逐步添加模板内容：尤其是表格循环部分，每次添加后测试，定位到触发报错的具体模板区域。
3. 校验传入数据：打印替换数据，确认所有模板引用的变量都存在且类型符合预期（比如字符串、数组等）。

内容的提问来源于stack exchange，提问作者Endless