campaign图片与附件实战base64内嵌、缓存机制与最佳实践清单【免费下载链接】campaign:love_letter: Compose responsive email templates easily, fill them with models, and send them out.项目地址: https://gitcode.com/gh_mirrors/ca/campaigncampaign是一个简单易用的 Node.js 邮件模板库编写响应式邮件模板、用数据模型填充、再发送出去。它的核心卖点之一就是把邮件中的图片以 base64 方式内嵌进邮件体配合进程级缓存机制避免重复读盘让收件人在离线环境下也能看到完整配图。下面这篇文章带你从零理解 campaign 处理图片与附件的完整原理并附一份可直接照做的最佳实践清单。为什么邮件图片要用 base64 内嵌传统网页里的img srchttps://...写法在邮件里并不可靠图片墙屏蔽多数邮件客户端默认拦截远程图片用户需要手动点显示图片离线不可见收件人断网或转发邮件后外链图片全部失效热链接失效外链资源被删除或域名变更后图片变成碎图标。campaign 的解法很直接把图片文件读出来编码成 base64 字符串内嵌进邮件通过cid:引用Content-ID关联。图片从此成为邮件的一部分不依赖任何外部地址。用默认布局发出去的效果长这样三种图片配置方式按场景对号入座1️⃣ 文件路径引用最常用在发送选项里通过images数组声明图片每项给name模板内引用名和file文件路径images: [ { name: housing, file: path.join(__dirname, housing.png) } ]模板里用img srccid:housing /即可命中这张图。官方测试用例 test/image.js 演示了完整写法images里声明{name:IMAGE, file: .../campaign.png}模板里写cid:IMAGE。2️⃣ 直接提供 base64 数据免去临时文件如果图片数据本来就在内存里比如刚由代码生成可以直接传data省掉创建临时文件的开销——但必须同时声明mimeimages: [ { name: housing, mime: image/png, data: buff.toString(base64) } ]hydrationService 会检测到data与mime同时存在直接跳过磁盘读取原样透传。3️⃣ 页头图片 headerImage客户端级配置创建 client 时可配置headerImage它会被编码后内嵌为邮件页头同样享受离线可见的好处。官方建议保持3:1 左右的比例例如 600x180避免在窄屏邮件客户端里被拉变形。每封邮件也可在model.headerImage中单独覆盖。附件 attachments与图片走不同的通道附件和图片是两码事——图片是内嵌进 HTML 的附件则是真正的 MIME 附件attachments: [ { name: invoice, file: path.join(__dirname, invoice.png) } ]发票、PDF 报告这类需要用户下载的文件走attachments需要在邮件里展示的图走images分工明确。缓存机制详解同一张图只读一次盘这是 src/imageEncodingCacheService.js 里最容易被忽略、却最实用的一段设计。它的核心是一个模块级全局缓存对象cache首次调用fs.readFile读取文件把 base64 数据与 MIME 类型存入cache[file]见 src/imageEncodingCacheService.js后续调用命中缓存直接走next()回调返回完全跳过文件 IO见 src/imageEncodingCacheService.js。对批量群发同一模板的场景意义重大给 1 万位收件人发同一封带配图的邮件图片文件只在进程生命周期内读取一次其余 9999 次全是内存命中发送吞吐不会被磁盘 IO 拖慢。⚠️ 注意两点缓存键是文件路径同一路径下的文件内容变更后本进程内不会自动失效缓存只针对文件路径模式data直传的图片不进缓存也不需要进。渲染管线图片在哪一步被编码了解管线位置出问题时才能快速定位。整个发送流程由 src/emailService.js 串行编排validation—— 校验收件人、主题src/validationService.jshydration—— 关键一步src/hydrationService.js 用contra.concurrent并发处理headerImage与images的 base64 编码同时把styles与默认样式合并render—— 模板引擎渲染 body再套上 layoutsrc/templateService.jsprovider.send—— 交给邮件服务商发出。也就是说编码发生在渲染之前模板引擎拿到的model.images已经是名字 MIME base64的成品引擎只负责生成cid:引用。图片与附件最佳实践清单✅照这份清单打勾基本不会再翻车正文配图一律用imagescid:不要在模板里写外链src内存中已有图片数据时直接传{ name, mime, data }避免临时文件页头图保持3:1 左右比例推荐 600x180控制体积在百 KB 内需要下载的文件发票、报告放attachments别误塞进images群发同模板前确认图片路径稳定吃下进程级缓存的红利用trap选项把测试邮件拦截到自己邮箱发前先肉眼看一遍图片是否正常开发期可换campaign-terminal服务商直接在终端查看 Markdown 版邮件快速验证布局。相关文件索引文件作用src/imageEncodingCacheService.jsbase64 编码 进程级缓存src/hydrationService.js并发编码页头图与正文图、合并样式src/emailService.js发送管线编排校验→注水→渲染→发送test/image.js图片内嵌的完整可运行示例resources/sample.pngcampaign 默认布局的实际邮件截图掌握base64 内嵌 缓存 正确区分图片与附件这三件事你的邮件在任意客户端、任意网络环境下都能体面呈现。【免费下载链接】campaign:love_letter: Compose responsive email templates easily, fill them with models, and send them out.项目地址: https://gitcode.com/gh_mirrors/ca/campaign创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 campaign图片与附件实战：base64内嵌、缓存机制与最佳实践清单
campaign图片与附件实战base64内嵌、缓存机制与最佳实践清单【免费下载链接】campaign:love_letter: Compose responsive email templates easily, fill them with models, and send them out.项目地址: https://gitcode.com/gh_mirrors/ca/campaigncampaign是一个简单易用的 Node.js 邮件模板库编写响应式邮件模板、用数据模型填充、再发送出去。它的核心卖点之一就是把邮件中的图片以 base64 方式内嵌进邮件体配合进程级缓存机制避免重复读盘让收件人在离线环境下也能看到完整配图。下面这篇文章带你从零理解 campaign 处理图片与附件的完整原理并附一份可直接照做的最佳实践清单。为什么邮件图片要用 base64 内嵌传统网页里的img srchttps://...写法在邮件里并不可靠图片墙屏蔽多数邮件客户端默认拦截远程图片用户需要手动点显示图片离线不可见收件人断网或转发邮件后外链图片全部失效热链接失效外链资源被删除或域名变更后图片变成碎图标。campaign 的解法很直接把图片文件读出来编码成 base64 字符串内嵌进邮件通过cid:引用Content-ID关联。图片从此成为邮件的一部分不依赖任何外部地址。用默认布局发出去的效果长这样三种图片配置方式按场景对号入座1️⃣ 文件路径引用最常用在发送选项里通过images数组声明图片每项给name模板内引用名和file文件路径images: [ { name: housing, file: path.join(__dirname, housing.png) } ]模板里用img srccid:housing /即可命中这张图。官方测试用例 test/image.js 演示了完整写法images里声明{name:IMAGE, file: .../campaign.png}模板里写cid:IMAGE。2️⃣ 直接提供 base64 数据免去临时文件如果图片数据本来就在内存里比如刚由代码生成可以直接传data省掉创建临时文件的开销——但必须同时声明mimeimages: [ { name: housing, mime: image/png, data: buff.toString(base64) } ]hydrationService 会检测到data与mime同时存在直接跳过磁盘读取原样透传。3️⃣ 页头图片 headerImage客户端级配置创建 client 时可配置headerImage它会被编码后内嵌为邮件页头同样享受离线可见的好处。官方建议保持3:1 左右的比例例如 600x180避免在窄屏邮件客户端里被拉变形。每封邮件也可在model.headerImage中单独覆盖。附件 attachments与图片走不同的通道附件和图片是两码事——图片是内嵌进 HTML 的附件则是真正的 MIME 附件attachments: [ { name: invoice, file: path.join(__dirname, invoice.png) } ]发票、PDF 报告这类需要用户下载的文件走attachments需要在邮件里展示的图走images分工明确。缓存机制详解同一张图只读一次盘这是 src/imageEncodingCacheService.js 里最容易被忽略、却最实用的一段设计。它的核心是一个模块级全局缓存对象cache首次调用fs.readFile读取文件把 base64 数据与 MIME 类型存入cache[file]见 src/imageEncodingCacheService.js后续调用命中缓存直接走next()回调返回完全跳过文件 IO见 src/imageEncodingCacheService.js。对批量群发同一模板的场景意义重大给 1 万位收件人发同一封带配图的邮件图片文件只在进程生命周期内读取一次其余 9999 次全是内存命中发送吞吐不会被磁盘 IO 拖慢。⚠️ 注意两点缓存键是文件路径同一路径下的文件内容变更后本进程内不会自动失效缓存只针对文件路径模式data直传的图片不进缓存也不需要进。渲染管线图片在哪一步被编码了解管线位置出问题时才能快速定位。整个发送流程由 src/emailService.js 串行编排validation—— 校验收件人、主题src/validationService.jshydration—— 关键一步src/hydrationService.js 用contra.concurrent并发处理headerImage与images的 base64 编码同时把styles与默认样式合并render—— 模板引擎渲染 body再套上 layoutsrc/templateService.jsprovider.send—— 交给邮件服务商发出。也就是说编码发生在渲染之前模板引擎拿到的model.images已经是名字 MIME base64的成品引擎只负责生成cid:引用。图片与附件最佳实践清单✅照这份清单打勾基本不会再翻车正文配图一律用imagescid:不要在模板里写外链src内存中已有图片数据时直接传{ name, mime, data }避免临时文件页头图保持3:1 左右比例推荐 600x180控制体积在百 KB 内需要下载的文件发票、报告放attachments别误塞进images群发同模板前确认图片路径稳定吃下进程级缓存的红利用trap选项把测试邮件拦截到自己邮箱发前先肉眼看一遍图片是否正常开发期可换campaign-terminal服务商直接在终端查看 Markdown 版邮件快速验证布局。相关文件索引文件作用src/imageEncodingCacheService.jsbase64 编码 进程级缓存src/hydrationService.js并发编码页头图与正文图、合并样式src/emailService.js发送管线编排校验→注水→渲染→发送test/image.js图片内嵌的完整可运行示例resources/sample.pngcampaign 默认布局的实际邮件截图掌握base64 内嵌 缓存 正确区分图片与附件这三件事你的邮件在任意客户端、任意网络环境下都能体面呈现。【免费下载链接】campaign:love_letter: Compose responsive email templates easily, fill them with models, and send them out.项目地址: https://gitcode.com/gh_mirrors/ca/campaign创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考