TRAE-AI编程
用 Vue3 在前端把页面导出成 word 文档时，最常见的翻车是：本地预览图片好好的，导出的 docx 里图片却是空白块。根因几乎都集中在“图片如何变成 word 能识别的二进制”这一步——图片没被正确内联、没加载完、或 docx 没登记图片部件，word 就显示空白占位。本文讲清三种可行写法，以及为什么你的那一版会空白，照着改就能让文档里的图稳定出现。先给结论：等 onload 后用 canvas 转 base64 内联，是最稳的写法。
一、先确认图片已加载再导出（前置与边界）
导出的第一道边界是：图片必须真正加载完成，否则 canvas 画出来的是空白。边界要划清：网络图要先下载、跨域图要带 crossOrigin、base64 图要等解码完成，三者都满足才能进导出流程。想系统学前端渲染，可参考 Vue3 教程。
理解这一点能避开最大误区：有人在 mounted 里立刻调用导出，此时 <img> 的 naturalWidth 还是 0，canvas 画出的就是一片空白。安装依赖并配置好导出库后，正确思路是监听图片 onload，等所有图就绪再生成 docx。配置上，若图片来自其它域名，服务端需返回允许跨域的响应头，否则画布会被污染、toDataURL 直接抛错。把“先就绪再导出”当成铁律，后面三种写法才不会白忙活。
实际项目里，导出往往不是单张图，而是一段带多张图的报告。所以前置要做一个“等全部图片就绪”的 Promise 集合，任何一张没好都先拦住导出。这个边界想清楚，后面无论用哪种内联写法，都不会再出现“部分图空白、部分图正常”的诡异情况，也方便接手的人照同一套等待逻辑处理新页面。
二、canvas 转 base64 内联（配置与运行）
最稳的写法是把图片转成 base64 后，以 data 协议直接内联进 word 的 XML 包。这样图片不依赖外部网络，docx 打开时一定能取到字节。运行命令前确认 canvas 尺寸按图片原始宽高设置。关于脚本与资源加载，可看 JavaScript 教程。
function imgToBase64(img) {
const canvas = document.createElement('canvas');
canvas.width = img.naturalWidth;
canvas.height = img.naturalHeight;
canvas.getContext('2d').drawImage(img, 0, 0);
return canvas.toDataURL('image/png');
}这种方式绕开了“图片跨域或被拦截”的问题，导出结果最稳定。canvas 把位图重绘成 PNG 字节，toDataURL 输出以 data:image/png;base64, 开头的字符串，docx 只要引用这段字节就能渲染。配置要点：给跨域图设 crossOrigin="anonymous"，否则画布被污染、转码失败。这个 base64 内联写法是导出 word 图片不空白的基石，优先采用。
实践里建议把转码封装成异步函数，等 onload 后再调用，返回 Promise<string>。这样在 Vue3 的导出方法里就能 await 多个图片的 base64，全部拿到再拼 docx。比起“同步硬转”，等就绪再转能保证每一张都是真实字节，而不是 0 宽高的空画布，也避免导出到一半因某张图未就绪而前功尽弃。
三、fetch 转 base64 的取舍（验证与预期）
如果你的图片都在同一域名且允许跨域，也可以用 fetch 取 blob 再转 base64，少一次 canvas 绘制。预期结果是：拿到和 canvas 同款的 data 字符串，只是路径不同。可看 HTML 教程 理解资源加载结构。
async function urlToBase64(url) {
const res = await fetch(url);
const blob = await res.blob();
return await new Promise((resolve) => {
const r = new FileReader();
r.onload = () => resolve(r.result);
r.readAsDataURL(blob);
});
}验证时对比两种写法输出的前缀是否都是 data:image/png;base64,，且长度明显大于原字符串。fetch 受 CORS 限制，跨域图会直接失败，所以内联 base64 更通用。它的同步写法观感不如 canvas 直接，但在“图片已在同源、只想省一次绘制”的场景里更轻量，属于按需选用，而不是一律替换，避免为了统一而引入跨域风险。
要注意 fetch 写法不能处理需要登录态的图片，除非请求里带上了凭证；而 canvas 写法读的是浏览器已加载的资源，天然带会话。验证数据流向时，可以在控制台打印两种 base64 的前 40 个字符，确认它们指向同一张图。把验证做扎实，导出 word 图片的方案才不会在边界处悄悄错位，也方便后续接手的人照着同样的方式排查空白问题。
四、三个常见坑与修复（失败与排错）
坑一：图片还没加载完就执行导出，naturalWidth 为 0，canvas 画出空白。解决是等 img.onload 后再转。坑二：跨域图片没设 crossOrigin，canvas 被污染，toDataURL 抛安全错误。样式相关可看 CSS 教程。
坑三：把图片当普通字符串拼进 HTML 模板，没有按 docx 的 relationships 登记图片部件，word 找不到图就显示空白占位。修复对应地：等 onload 再转、给跨域图设 crossOrigin、在生成 docx 时把 base64 注册为媒体部件并写对引用关系。失败分支里最隐蔽的是“看似写了 img 其实没登记”，用打包后的 docx 解压看 word/media 目录，确认图片字节真的在。
还有一个坑：直接把 <img src="网络地址"> 写进 docx，指望 word 自己下载——多数情况下 word 出于安全策略不拉取外部图，于是空白。失败修复时，统一走 base64 内联，彻底去掉对外部网络的依赖。把这类边界写进导出封装里，调用方拿到的 docx 无论在哪一台机器打开，图片都稳定可见，体验比裸引外链更稳。
五、适用边界与替代方案（安全与对比）
canvas 转 base64 适合“图片已在页面、要稳定进 docx”的场景；若图片量极大、base64 会让文档体积暴涨，可考虑先把图上传到对象存储拿 URL，再用支持外链的 docx 方案。对比来看，内联换的是体积，外链换的是离线可用性。关于保存可复现示例，可看 Git 版本控制。
适用边界上：少量关键图（截图、图表）用 base64 内联最稳；大批量图建议上传后引用。安全上，base64 不含凭证、不会泄露会话，但体积要控制，单文档别塞几十张高清图。导出 word 图片的本质是“让字节跟着文档走”，把边界和替代方案想清楚，Vue3 导出的文档才不会既大又容易空白。
从工程安全角度，转 base64 前先校验图片类型，拒绝非图片的 data，避免把错误字节写进 docx 导致文件损坏。更好的做法是封装一个导出函数，内部完成“等就绪 → 转码 → 登记 → 组装”，对外只暴露一个方法。这样导出 word 图片既是可用性工具，也是稳定性工具：它让文档里的图稳定可见，又保留了代码不依赖外部网络的本质优势（编辑推断）。
总结
Vue3 导出 word 图片空白，九成是图片没被正确内联成 base64，或导出时图还没加载完、跨域被污染、docx 没登记图片部件。最稳的写法是等 onload 后用 canvas 转 base64 内联；避开跨域裸引和外链图，文档里的图就能稳定出现。
常见问题
Q：为什么本地预览有图、导出就空白？
预览读的是浏览器已加载的资源，导出时如果图未就绪或跨域被拦，转出来的字节就是空的。
Q：网络图片直接写进 docx 行不行？
多数 word 出于安全策略不会主动下载外部图，容易空白，建议统一转 base64 内联。
Q：canvas 转 base64 报安全错误怎么办？
给图片设 crossOrigin="anonymous" 并确保服务端允许跨域，否则画布被污染无法导出。
