自定义模板导出失败主因是字段名不一致，需严格匹配大小写与嵌套语法；Excel乱码因编码设置错误；模板语法跨引擎不兼容；大数据量须用流式导出。
导出时模板字段和数据源字段对不上
字段名不一致是自定义模板导出失败最常见原因，不是模板写得不对，而是插件默认按字段名严格匹配。比如数据源里是 user_name，但模板里写了 username 或 name，导出结果就为空或报错 field not found: username。
实操建议：
- 先用插件的「预览映射」功能（如果有）查看实际可用字段列表，别凭经验猜
- 字段名区分大小写，
id和ID是两个字段 - 嵌套字段如
user.profile.email需确认插件是否支持点号语法；不支持时得提前在数据源里扁平化成user_email - 部分插件要求模板中字段必须出现在数据源返回的 JSON Schema 里，动态生成的字段（如计算列）要手动声明
Excel 导出后中文乱码或格式错乱
这不是模板问题，而是导出插件对 charset 和 Content-Type 的处理逻辑差异导致的。尤其用 Node.js 后端调用 exceljs 或 Python 用 pandas.DataFrame.to_excel 时，没显式指定编码或工作表类型，就会出现数字变科学计数、日期变数字、中文显示为方块。
实操建议：
- 导出 Excel（
.xlsx）时，禁用utf-8-sig编码——它只对 CSV 有效，对 XLSX 反而触发 Excel 兼容异常 - 用
exceljs时，确保workbook.creator设为字符串，否则某些版本会静默失败 - 如果导出含公式或样式，模板里不要混用
string和number单元格类型；同一列尽量保持类型一致，否则 Excel 自动转换会丢精度 - CSV 导出想保中文？HTTP 响应头必须带
Content-Type: text/csv; charset=utf-8，且文件开头加 BOM（\ufeff），否则 Excel 打开就是乱码
模板语法在不同插件里行为不一致
同一个 {{ user.name }} 在 Vue 模板引擎、Handlebars、或插件自研的轻量模板里，渲染逻辑可能完全不同：有的自动转义 HTML，有的不处理 null，有的不支持三元表达式。你写的模板在 A 插件能跑，在 B 插件导出空值，大概率是语法兼容性问题。
实操建议：
- 查清插件文档里明确写的模板引擎名称，比如
mustache不支持{{#if}}，但handlebars支持 - 避免用复杂表达式，
{{ user.age > 18 ? 'adult' : 'minor' }}在多数轻量模板里直接报错，换成预处理字段user.status更稳 - null/undefined 值默认渲染为空字符串，但有些插件会输出
"null"字面量，需用{{#user.name}}{{user.name}}{{/user.name}}这类条件块兜底 - 路径中含数组时，
{{ users.[0].name }}写法在部分插件里非法，得改用{{ users.0.name }}或走循环语法
导出大文件时内存溢出或超时
用模板拼接整个数据集再一次性写入文件，数据量一过万条，Node.js 就容易 OOM，PHP 可能 hit max_execution_time，浏览器端直接卡死。这不是模板写得不好，是导出模式选错了。
实操建议：
- 超过 5000 行，放弃「全量渲染模板 → 生成字符串 → 写文件」流程，改用流式导出（streaming export）
- 用
exceljs时开启stream: true并配合writeRow()逐行写，别用addRows()一次性塞数组 - 后端 API 不要返回完整文件二进制，而是返回
Content-Disposition: attachment+ 流式响应体，前端用fetch+ReadableStream接收，避免内存堆积 - 模板里禁止使用
{{ loop over huge array }}这种写法，把聚合逻辑提到数据准备阶段，模板只做展示层映射
真正难的不是写模板，是搞清楚你用的那个插件到底把模板编译成了什么、字段从哪来、字节怎么落盘。很多问题卡住，是因为在 debug 模板语法，其实该去看网络响应头或内存快照。
