Docxtemplater中异步获取图片尺寸导致导出Word图片丢失问题解析

问题现象

在使用Docxtemplater进行Word文档生成时，开发者遇到了一个典型问题：当在getSize回调函数中使用Promise异步获取图片尺寸时，预览功能可以正常显示图片，但在最终导出的Word文档中图片却丢失了。而如果直接返回固定尺寸如[600,400]，则图片能够正常显示。

问题根源

这个问题的根本原因在于Docxtemplater的同步渲染机制与异步操作的不兼容性。Docxtemplater默认的render方法是同步执行的，当遇到异步操作（如Promise）时，无法正确等待异步操作完成就继续执行后续流程，导致图片尺寸信息未能及时获取。

解决方案

针对这个问题，Docxtemplater提供了专门的异步渲染API——renderAsync。这个API能够正确处理包含Promise的异步操作，确保所有异步操作完成后再生成最终文档。

正确用法示例

const fs = require('fs');
const Docxtemplater = require('docxtemplater');

const content = fs.readFileSync(__dirname + "/template.zip", "binary");
const zip = new PizZip(content);
const doc = new Docxtemplater(zip);

// 使用renderAsync替代render
doc.renderAsync({
    // 插入数据
}).then(function() {
    const buf = doc.getZip().generate({type:"nodebuffer"});
    fs.writeFileSync(__dirname+"/output.docx",buf);
});

getSize回调函数的实现

opts.getSize = (img, tagValue, tagName) => {
    return new Promise(function (resolve) {
        var image = new Image();
        image.src = tagValue;
        image.onload = function() {
            resolve([image.width, image.height]);
        };
        image.onerror = function(e) {
            console.error('图片加载失败', e);
            // 可以提供默认尺寸作为fallback
            resolve([600, 400]);
        };
    });
};

技术原理

Docxtemplater的同步渲染机制设计初衷是为了简化大多数简单场景的使用。但在处理需要异步操作（如图片尺寸获取、网络请求等）时，就需要使用异步API。renderAsync方法内部会跟踪所有Promise的完成状态，确保所有异步操作都完成后再进行文档生成。

最佳实践建议

1. 当模板中包含需要异步处理的内容（如图片、外部数据等）时，统一使用renderAsync
2. 在getSize回调中实现良好的错误处理，提供合理的默认值
3. 对于性能敏感场景，可以考虑缓存已获取的图片尺寸
4. 在浏览器环境中使用时，注意图片跨域问题可能导致的尺寸获取失败

总结

Docxtemplater作为一款强大的Word模板处理库，通过区分同步和异步API来适应不同场景需求。理解其异步处理机制，正确使用renderAsync方法，可以解决因异步操作导致的图片丢失等问题，使文档生成更加可靠和灵活。