将 @nestjs-modules/mailer 从 3.x 升级到 4.x

根据 TypeScript 类型自动比较 @nestjs-modules/mailer 3.0.2 与 4.0.0 的公开 API。签名变化表示可能存在不兼容变更，并非确定结论。

概要

已删除的导入路径	0
已删除的导出	0
已修改的签名	0
已删除的类或接口成员	1
已修改的类或接口成员	3
新增弃用	0
要求变化（engines、peer 依赖）	3
新增导出	64

已删除的导出

未发现。

已修改的签名

未发现。

已删除的类或接口成员

member	import	之前
`MailerService.executeSend`	`@nestjs-modules/mailer`	`any`

已修改的类或接口成员

member	之前	之后
`MailerService.constructor`	`(mailerOptions: MailerOptions, transportFactory: MailerTransportFactory, eventService?: MailerEventService \| undefined): MailerService`	`(mailerOptions: MailerOptions, transportFactory?: MailerTransportFactory \| undefined, eventService?: MailerEventService \| undefined, moduleRef?: any): MailerService`
`MailerTestModule.static register`	`(options?: Partial<{ template: { dir?: string \| undefined; adapter?: any; options?: any; }; }> \| undefined): DynamicModule`	`(options?: Omit<MailerOptions, "transport" \| "transports"> \| undefined): DynamicModule`
`MailerEventService.constructor`	`(eventEmitter?: any): MailerEventService`	`(eventEmitter?: MailerEventEmitter \| undefined, moduleRef?: any): MailerEventService`

新增弃用

未发现。

要求变化（engines、peer 依赖）

	之前	之后
`peerDependencies.handlebars`	`>=4.7.9`	`>=4.7.10`
`peerDependencies.@nestjs/mail`	`—`	`>=0.0.1`
`peerDependencies.@nestjs/outbox`	`—`	`>=0.1.3`

新增导出 (64)

import	export	kind
`@nestjs-modules/mailer`	`html`	function
`@nestjs-modules/mailer`	`signV4`	function
`@nestjs-modules/mailer`	`Mailable`	interface
`@nestjs-modules/mailer`	`SafeHtml`	class
`@nestjs-modules/mailer`	`MailQuery`	interface
`@nestjs-modules/mailer`	`htmlToText`	function
`@nestjs-modules/mailer`	`isSafeHtml`	function
`@nestjs-modules/mailer`	`unsafeHtml`	function
`@nestjs-modules/mailer`	`MailerError`	class
`@nestjs-modules/mailer`	`TestMailbox`	class
`@nestjs-modules/mailer`	`CapturedMail`	class
`@nestjs-modules/mailer`	`LogTransport`	class
`@nestjs-modules/mailer`	`MailableData`	type
`@nestjs-modules/mailer`	`RenderedMail`	interface
`@nestjs-modules/mailer`	`SesTransport`	class
`@nestjs-modules/mailer`	`SigV4Options`	interface
`@nestjs-modules/mailer`	`SigV4Request`	interface
`@nestjs-modules/mailer`	`FileTransport`	class
`@nestjs-modules/mailer`	`MailerPreview`	type
`@nestjs-modules/mailer`	`toMailerError`	function
`@nestjs-modules/mailer`	`AwsCredentials`	interface
`@nestjs-modules/mailer`	`BrevoTransport`	class
`@nestjs-modules/mailer`	`SigV4Signature`	interface
`@nestjs-modules/mailer`	`LOCAL_TRANSPORT`	variable
`@nestjs-modules/mailer`	`MailableContent`	type
`@nestjs-modules/mailer`	`MailableContext`	interface
`@nestjs-modules/mailer`	`MailerSmtpError`	class
`@nestjs-modules/mailer`	`ResendTransport`	class
`@nestjs-modules/mailer`	`parseRetryAfter`	function
`@nestjs-modules/mailer`	`validateMessage`	function
`@nestjs-modules/mailer`	`InterceptOptions`	interface
`@nestjs-modules/mailer`	`MailgunTransport`	class
`@nestjs-modules/mailer`	`isTransientError`	function
`@nestjs-modules/mailer`	`MailerEventRecord`	interface
`@nestjs-modules/mailer`	`PostmarkTransport`	class
`@nestjs-modules/mailer`	`SendGridTransport`	class
`@nestjs-modules/mailer`	`mailerChannelName`	function
`@nestjs-modules/mailer`	`MailerEventEmitter`	interface
`@nestjs-modules/mailer`	`MailerMessageError`	class
`@nestjs-modules/mailer`	`MailerRetryOptions`	interface
`@nestjs-modules/mailer`	`MailerTimeoutError`	class
`@nestjs-modules/mailer`	`UnsubscribeOptions`	interface
`@nestjs-modules/mailer`	`HttpSentMessageInfo`	interface
`@nestjs-modules/mailer`	`LogTransportOptions`	interface
`@nestjs-modules/mailer`	`MailableSendOptions`	type
`@nestjs-modules/mailer`	`MailerPreviewModule`	class
`@nestjs-modules/mailer`	`MailerProviderError`	class
`@nestjs-modules/mailer`	`MailerTemplateError`	class
`@nestjs-modules/mailer`	`SesTransportOptions`	interface
`@nestjs-modules/mailer`	`FileTransportOptions`	interface
`@nestjs-modules/mailer`	`HttpTransportOptions`	interface
`@nestjs-modules/mailer`	`MAILER_EVENT_EMITTER`	variable
`@nestjs-modules/mailer`	`MailerPreviewOptions`	interface
`@nestjs-modules/mailer`	`mayHaveBeenDelivered`	function
`@nestjs-modules/mailer`	`BrevoTransportOptions`	interface
`@nestjs-modules/mailer`	`HttpProviderTransport`	class
`@nestjs-modules/mailer`	`MailerConnectionError`	class
`@nestjs-modules/mailer`	`SuppressedMessageInfo`	interface
`@nestjs-modules/mailer`	`MAILER_PREVIEW_OPTIONS`	variable
`@nestjs-modules/mailer`	`ResendTransportOptions`	interface
`@nestjs-modules/mailer`	`MailgunTransportOptions`	interface
`@nestjs-modules/mailer`	`PostmarkTransportOptions`	interface
`@nestjs-modules/mailer`	`SendGridTransportOptions`	interface
`@nestjs-modules/mailer`	`MailerRecipientsRejectedError`	class

这些版本之间的 changelog

软件包作者发布的文本，按原样显示。

4.0.0

### Major Changes

- [#1353](https://github.com/nest-modules/mailer/pull/1353) [`c8c0423`](https://github.com/nest-modules/mailer/commit/c8c0423749bd8f0f7d0f247e62ee5ab7a55f6535) Thanks [@juandav](https://github.com/juandav)! - v4: everything the official `@nestjs/mail` offers and more, without dropping anything v3 supports. Every capability is optional: use nodemailer, the built-in HTTP providers or `@nestjs/mail`'s transports; send directly, through BullMQ or through `@nestjs/outbox`; call `sendMail`, mail classes or the official `Mailer` over this module.
  
  **Breaking changes** (see the [migration guide](https://nest-modules.github.io/mailer/guide/migration)):
  
  - Transient failures are retried by default (3 attempts with backoff); `retry: false` restores v3. A timeout or a dropped connection while the message was being handed over is retried only when the email has a stable Message-ID (`idempotencyKey`), so nothing is sent twice. `sendTimeout` applies per attempt.
  - Errors from transports are typed (`MailerSmtpError`, `MailerTimeoutError`, … all `MailerError`), keeping nodemailer's fields and the original as `cause`; `wrapErrors: false` restores v3.
  - Emails without a text part get one derived from the HTML (`textFromHtml: false` to opt out), and messages are validated before sending (`validate: false` to opt out).
  - `MailerTestModule` delivers to a `TestMailbox` (no stream transport; `info.message` uses CRLF line endings) and defaults `retry` to `false`.
  - `MailerPreviewModule` is on by default only when `NODE_ENV` is `development` or `test`.
  - Event payloads carry `attempt`, `permanent`, `transporterName` and `durationMs`; `MailerEventService` takes its emitter through `MAILER_EVENT_EMITTER`, and `EventEmitter2` is found automatically (in v3 it was never injected).
  - `MailableContext.to` is `{ name?, address }[]`, the same shape as `@nestjs/mail`.
  
  **New**
  
  - Mail classes (`mailerService.send(WelcomeMail, { to, data })`) compatible with `@nestjs/mail`'s, with dependencies resolved from the whole app, and `render()` to render without sending.
  - Retries with backoff and error classification (nodemailer, HTTP and AWS SDK errors), failover between transporters, `AbortSignal`, `idempotencyKey`, and graceful shutdown that waits for sends in flight (`shutdownTimeout`).
  - Zero-dependency HTTP transports: Resend, Postmark, SendGrid, SES (SigV4), Mailgun and Brevo.
  - The `html` tagged template (`unsafeHtml()` for trusted markup), `htmlToText()` and message validation.
  - `intercept` (redirect recipients in staging), `suppress` (suppression lists) and one-click `unsubscribe` (RFC 8058).
  - `TestMailbox` with assertions, `FileTransport` and `LogTransport` (with a warning when used in production) and `MailerPreviewModule` to preview emails in the browser.
  - `events$`, `node:diagnostics_channel` publishing (credentials redacted), and `RETRY`, `FAILOVER` and `SUPPRESSED` events.
  - BullMQ: permanent failures fail the j

把这些数据交给你的 AI 智能体

Vigia 是免费的 MCP 服务器：你的编程智能体在写代码之前就能检查版本、不兼容变更和安全漏洞。无需注册，无需 API 密钥。

claude mcp add --transport http vigia https://vigia.coredls.cloud/mcp

添加到 Cursor 添加到 VS Code ★ 在 GitHub 上加星

任何其他 MCP 客户端

{ "mcpServers": { "vigia": { "url": "https://vigia.coredls.cloud/mcp" } } }

智能体技能（SKILL.md）：告诉智能体何时使用 Vigia · 用于拉取请求的 GitHub Action

常见问题

将 @nestjs-modules/mailer 从 3 升级到 4 有哪些不兼容变更？

在 @nestjs-modules/mailer 3.0.2 与 4.0.0 之间，Vigia 发现 0 个已删除的导出、0 个已修改的签名，以及 4 个已删除或修改的类或接口成员。

@nestjs-modules/mailer 4 中弃用了哪些内容？

@nestjs-modules/mailer 4.0.0 中有 0 个导出或成员新被标记为弃用。

供智能体使用

GET https://vigia.coredls.cloud/v1/packages/npm/@nestjs-modules/mailer/upgrade?from=3.0.2&to=4.0.0