# @growth-labs/mailer 中文文档

规范地址：https://npmcn.com/package/%40growth-labs/mailer/

版本：0\.8\.2
npm 元数据更新时间：2026-10-27T14:33:29.896Z
中文译文更新时间：2026-11-17T08:54:08.642Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40growth-labs/mailer
原文对照：https://npmcn.com/package/%40growth-labs/mailer/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：511 kB，191 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：astro ^6\.1\.10 \|\| ^7\.0\.0
- 首次发布：2026-04-13T14:32:09.184Z
- 最新版本发布：2026-10-27T14:33:29.535Z
- 近 30 天下载量：4945（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

基于队列的Astro + Cloudflare 电子邮件发送引擎. 通讯订阅有双选入,活动发送,开放/点击跟踪,不订阅管理. 使用 Cloudflare Quees 来进行Aync送出.

## 安装

```sh
npm install @growth-labs/mailer
```

也可以使用：`pnpm add @growth-labs/mailer`、`yarn add @growth-labs/mailer`、`bun add @growth-labs/mailer`

## README

# @ growth-labs/ 邮件

基于队列的Astro + Cloudflare 电子邮件发送引擎. 通讯订阅有双选入,活动发送,开放/点击跟踪,不订阅管理. 使用 Cloudflare Quees 来进行Aync送出.

**"发动机,不是司机。"** 此软件包发送邮件 。 寄送什么,消费者关心的是谁(如:. `@fulcrum/dispatch` 层层编辑智能在上.

如果您只需要从没有用户状态或队列的工人那里立即发送交易, 请使用 `@growth-labs/email` 换句话说.

Astro 6 注: 注入的路由为 D1 和队列绑定 `cloudflare:workers` `env`; 无 `locals.runtime` shim是必须的.

## 何时使用此 vs `@growth-labs/email`

使用 `@growth-labs/mailer` (本套)用于通讯和宣传活动 工作流程。 使用 `@growth-labs/email` 交易一次性发送. 见 `@growth-labs/email` 读取完全区分.

两种集成程序都通过 阿斯特罗的 `astro:config:done` 类型注射。 任何消费者拥有的申报 所需经费 `virtual:growth-labs/mailer/config`;运行时路由选择不变.

## 配置

```typescript
import mailer from '@growth-labs/mailer'

mailer({
  senderName: 'FEDweek',
  fromAddress: 'newsletter@fedweek.com',
  replyTo: 'editors@fedweek.com',
  d1Binding: 'SITE_DB',
  queueBinding: 'EMAIL_QUEUE',
  turnstileSiteKey: '...',
  turnstileSecretBinding: 'TURNSTILE_SECRET_KEY', // Optional; this is the default
  doubleOptIn: true,
  topics: ['daily-digest', 'breaking-news'],     // Optional topic-based subscriptions
  signingSecretBinding: 'MAILER_SIGNING_SECRET', // Optional; this is the default
  siteUrl: 'https://fedweek.com',
  brand: {
    logoUrl: 'https://media.fedweek.com/logos/email.png',
    primaryColor: '#1a365d',
    accentColor: '#e53e3e',
    footerText: '© FEDweek. All rights reserved.',
  },
  analyticsEnabled: true,                        // Emit email events to @growth-labs/analytics
  analyticsBinding: 'ANALYTICS',                 // WAE binding used when analytics is enabled
  webhookSignature: {
    enabled: true,
    secret: import.meta.env.MAILER_WEBHOOK_SECRET,
  },
})
```

这项合并登记了下列通讯路线和组成部分. 对于新订阅者,订阅路由会记录订阅者并发送一个 何时确认电子邮件 `doubleOptIn` 已启用,或未启用的欢迎电子邮件.

### 没有交货路线的部件

使用 `mailerComponents` 改为 `mailer` 渲染时 `SubscribeForm` 与 由消费者拥有的端点,或者在私人预览中无法交付:

```typescript
import { mailerComponents } from '@growth-labs/mailer'

mailerComponents({
  turnstileSiteKey: 'public-site-key',
  subscribePath: '/api/newsletter/subscribe', // Optional; this is the default
  topics: ['daily-digest'],                 // Optional
})
```

这只安装现有的窗体配置 Vite 插件 。 它不会注射 路径或跟踪中间软件,不需要D1、队列、发送者或秘密绑定. 只有这三种公开选项被接受;秘密和交付选项失败 审定。 表格仍提交给 `subscribePath`: 此整合没有 执行订阅交付或禁用窗体。 消费者必须提供 Turnstile 被保护的端点, 或在其私人预览中保持无法发送 . 每个站点选择一个邮件集成. 默认 `mailer` 合并保留 它的全程,中间软件和运行时的安全行为.

## 生产模式

**`from` 对 `replyTo`。 。 。 .** 一个常见的模式是 `fromAddress: 'noreply@mail.site.com'` 配对 `replyTo: 'hello@site.com'`编辑 `from` 住在你用 Cloudflare Email Sending(通常为 `mail.` 子域 ; `replyTo` 在真正的人类收件箱读取器的分数可以回信. `replyTo` 也是每个消息覆盖 `sendTransactional` 和每个现场 `SiteMailerConfig` (真实模式,自0.4.0起).

**别烤回扣 `fromAddress`。 。 。 .** 计划需要有效的电子邮件( Name`z.string().email()`和船舶没有默认,这是故意的。 消费者的后退就像 `process.env.MAILER_FROM_ADDRESS ?? 'hello@site.com'` 是一个脚枪: 如果在部署时缺少了 env var , 返回域可能没有通过 Cloudflare 电子邮件发送验证, 每一份发送返回 `unauthorized_sender`,排队重复,直到预算杀死消息。 失败了在建造/部署 当内脏不见了 —— 计划不能赶上你的后退.

**秘密会按要求解决的.** 捆绑 `TURNSTILE_SECRET_KEY` 财务报告和审定财务报表 `MAILER_SIGNING_SECRET` 在工人号上。 普通工人秘密和秘密存储库 绑定都支持; 密钥存储绑定用 Aync 读取 `.get()` 并每个隔离处缓存。 缺少或空生产绑定在503个之前返回 订阅者写作. Build-time 字面选项在本地主机外被忽略 .

## 输入什么

**路线 :**

-   `POST /api/newsletter/subscribe` - 受转弯保护的订阅
-   `GET /api/newsletter/confirm?token=...` - 双重选择加入确认
-   `GET /api/newsletter/unsubscribe?token=...` ——一击取消订阅
-   `GET/POST /email/preferences?token=...` ——首选中心页
-   `POST /api/email/webhook` - ESP 网页接收器(交付、回弹、投诉),可选的HMAC签名验证
-   `GET /api/email/open/:trackingId` ——开放跟踪像素
-   `GET /api/email/click/:trackingId` - 点击跟踪方向

**组件 :**

-   `<SubscribeForm />` - 带有Turnstile的通讯注册表
-   `<PreferenceCenter />` - 专题订阅管理

## D1 表格(前缀) `gl_`(中文(简体) )

-   `gl_subscribers` ——订阅者记录(电子邮件,名称,状态,议题,已确认 at)
-   `gl_email_sends` — 发送日志( 状态: 队列已到 ) – 已发送 – 已发送 – 已打开 – 已点击 )

## 装订

```toml
[[d1_databases]]
binding = "SITE_DB"
database_id = "..."

[[queues.producers]]
binding = "EMAIL_QUEUE"
queue = "email-sends"

[[queues.consumers]]
queue = "email-sends"
max_batch_size = 10

[[analytics_engine_datasets]]
binding = "ANALYTICS"
dataset = "your_analytics_dataset"

[[secrets_store_secrets]]
binding = "TURNSTILE_SECRET_KEY"
store_id = "..."
secret_name = "your-turnstile-secret"

[[secrets_store_secrets]]
binding = "MAILER_SIGNING_SECRET"
store_id = "..."
secret_name = "your-mailer-signing-secret"
```

## 电子邮件发送流程

1.  消费者电话 `sendTransactional()`, (中文(简体) ), `sendCampaign()`,或 `sendDigest()` ~ 信息排队
2.  通过 Cloudflare Email 发送 与可重试失败的重试
3.  更新状况 `gl_email_sends`: 队列已出 出 出 出/出
4.  进一步打开/点击跟踪更新状态

## 密钥模式

-   虚拟模块 : `virtual:growth-labs/mailer/config`
-   运行时间绑定 : `import { env } from 'cloudflare:workers'`
-   情况从未降级(已发到)
-   每封邮件( RFC 8058) 上列表- 取消订阅页眉
-   在订阅端点上转动( + IP 速率限制为备份)
-   为可观察性而登录的提供者故障
-   WAE事件通过配置的Analytics引擎捆绑——火与遗忘,非阻塞,并兼容其装订物 `writeDataPoint()` 返回时 `void`
-   Cloudflare 电子邮件发送使用当前结构 `html` 有效载荷和远期 `replyTo` 加自定义标题到绑定
-   `.astro` 组件文件为源文件, 未编译

## 分析事件

何时 `analyticsEnabled` 真实和配置 `analyticsBinding` 数据点 `newsletter_subscribed`, (中文(简体) ), `newsletter_confirmed`, (中文(简体) ), `newsletter_unsubscribed`, (中文(简体) ), `newsletter_opened`, (中文(简体) ), `newsletter_clicked`, (中文(简体) ), `newsletter_delivered`, (中文(简体) ), `newsletter_bounced`, (中文(简体) ), `newsletter_complained`, (中文(简体) ), `newsletter_sent`,以及 `newsletter_send_failed`。 。 。 .

## 常见问题

### @growth-labs/mailer 是什么？

基于队列的Astro \+ Cloudflare 电子邮件发送引擎\. 通讯订阅有双选入,活动发送,开放/点击跟踪,不订阅管理\. 使用 Cloudflare Quees 来进行Aync送出\.

### 如何安装 @growth-labs/mailer？

在项目目录运行 npm install @growth-labs/mailer，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：astro（^6\.1\.10 \|\| ^7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @growth-labs/mailer 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @growth-labs/mailer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @growth-labs/mailer 可以商用吗？

@growth-labs/mailer 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @growth-labs/mailer 的下载量有多少？

根据 npm 官方下载统计，@growth-labs/mailer 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,945 次，日均约 165 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @growth-labs/mailer 还在维护吗？

最新版本 0\.8\.2 发布于 2026/10/27（20 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/04/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

