使用 node-canvas 时，若文字显示在图片下方，根本原因是绘制顺序错误——必须先绘制背景图像，再绘制文字；否则异步加载的图像会覆盖已绘制的文字。本文详解正确渲染顺序、关键注意事项及健壮实现方案。
使用 node-canvas 时，若文字显示在图片下方，根本原因是绘制顺序错误——必须先绘制背景图像，再绘制文字；否则异步加载的图像会覆盖已绘制的文字。本文详解正确渲染顺序、关键注意事项及健壮实现方案。
在 node-canvas 中实现“图像为背景 + 文字叠加”的效果，核心在于严格控制绘制时序。Canvas 是基于栅格的立即模式绘图 API，所有绘制操作按代码执行顺序逐层叠加（后绘制的内容覆盖先绘制的内容）。原代码中，fillText() 调用在 loadImage().then(...) 外部同步执行，而 loadImage 是异步操作，导致文字先被画出，随后加载完成的图像再通过 fillRect() 全屏填充——自然将文字完全遮盖。
✅ 正确做法是：将所有前景内容（文字、形状等）的绘制逻辑，全部移入 loadImage 的 then 回调内部，确保图像已加载并绘制为背景后，再进行文字渲染。
以下是优化后的完整示例（含错误处理与最佳实践）：
const { createCanvas, loadImage } = require("canvas");
const fs = require("fs");
const width = 848;
const height = 600;
const canvas = createCanvas(width, height);
const ctx = canvas.getContext("2d");
// ✅ 关键：所有绘制操作均在图像加载完成后执行
loadImage("./assets/jimp-cert-template.jpg")
.then((image) => {
// 1. 绘制背景：拉伸填充全画布（非平铺）
ctx.fillStyle = ctx.createPattern(image, "no-repeat");
// ⚠️ 注意：createPattern 默认不缩放；如需铺满，应使用 drawImage
ctx.fillRect(0, 0, width, height);
// 2. 设置文字样式（建议统一配置）
ctx.font = "bold 70pt 'PT Sans', sans-serif";
ctx.textAlign = "center";
ctx.textBaseline = "middle"; // 更精准的垂直对齐
ctx.fillStyle = "#764abc";
// 3. 绘制标题（坐标需根据实际布局调整）
ctx.fillText("TITLE 1", 600, 170);
ctx.font = "bold 100pt 'PT Sans', sans-serif";
ctx.fillText("TITLE 2", 600, 270);
// 4. 输出图像
const buffer = canvas.toBuffer("image/jpeg", { quality: 0.95 });
fs.writeFileSync("./image.jpeg", buffer);
console.log("✅ Certificate generated successfully!");
})
.catch((err) => {
console.error("❌ Failed to load or render image:", err);
process.exit(1);
});
? 重要注意事项：
-
字体可靠性：
'PT Sans'需提前在系统安装，或使用registerFont()加载本地.ttf文件，否则回退到默认字体，影响排版。 -
图像缩放建议：
createPattern(..., "no-repeat")不会自动缩放图像。如需背景图完全覆盖画布，推荐改用ctx.drawImage(image, 0, 0, width, height)。 -
坐标调试技巧：启用
ctx.strokeStyle = "red"; ctx.strokeRect(x-50, y-30, 100, 60);可临时框出文字区域，快速校准位置。 -
异步安全：切勿在
loadImage外部访问image或调用ctx方法——这是典型的竞态错误根源。
遵循“背景 → 前景”单向绘制流，配合完善的错误处理与字体管理，即可稳定产出高质量图文合成图像。
