EmDash 使用电子邮件进行魔法链接登录、用户邀请和帐户恢复。由提供商传递邮件:可以是 EmDash 内置的 SMTP 传输,也可以是提供商插件。
本指南涵盖电子邮件管道的工作原理、开发中开箱即用的功能以及如何为生产环境连接真实提供商。
电子邮件传递的工作原理
单个活动提供商传递所有出站邮件。如果没有活动提供商,需要电子邮件的功能将不可用,邀请链接必须从用户页面手动复制和共享。
您可以在管理面板的 Settings → Email 下查看当前状态:提供商是否处于活动状态、是哪个提供商,以及一个 send test email 按钮,用于测试完整管道。
开发环境:内置控制台提供商
在开发环境(astro dev)中,当没有其他活动提供商时,EmDash 会自动激活内置控制台提供商。它不发送任何内容 — 它将每封电子邮件记录到终端,并将最后 100 条消息保留在内存中。
这意味着魔法链接和邀请在开发环境中开箱即用:请求魔法链接,然后从终端输出中复制 URL。您还可以在仅限开发的端点 GET /_emdash/api/dev/emails 列出捕获的电子邮件(并使用 DELETE 清除它们)。
如果在添加提供商插件或设置 SMTP 之后,Settings → Email 仍显示控制台,请在那里选择该提供商并保存。
控制台提供商仅用于开发,永远不会在生产构建中运行。
生产环境:内置 SMTP 传输
如果您有 SMTP 凭证(例如 Brevo、Office 365、Fastmail、Amazon SES 或您自己的邮件服务器),EmDash 无需插件即可通过它们发送邮件。该传输在认证之前要求使用 TLS,支持 AUTH PLAIN 和 AUTH LOGIN,并拒绝 25 端口。
您可以通过以下两种方式之一进行配置:
- 在管理后台: 打开 Settings → Email,选择 SMTP,填写服务器详细信息并保存。保存时会将设置存入数据库并选中 SMTP。EmDash 使用
EMDASH_ENCRYPTION_KEY加密密码,因此必须设置该密钥。在管理后台保存的设置优先于环境变量,因此轮换密码时请在管理后台修改。 - 使用环境变量: 在服务器的进程环境中设置以下变量。在 Cloudflare 上使用
wrangler secret put,本地开发使用.env。在 Node 上,astro dev和构建后的服务器都不会加载.env,因此请导出这些变量,或使用node --env-file=.env启动服务器。请参阅 Secrets & Key Management。
| 变量 | 示例 | 说明 |
|---|---|---|
EMAIL_SMTP_HOST | smtp.example.com | 必填 |
EMAIL_SMTP_PORT | 587 | 可选;默认 587。隐式 TLS 使用 465 |
EMAIL_SMTP_USER | [email protected] | 必填;SMTP 登录名 |
EMAIL_SMTP_PASS | your-smtp-password | 必填;请将其存为密钥 |
EMAIL_SMTP_SECURE | tls 或 starttls | 可选;465 端口使用 tls,其他所有端口使用 starttls |
EMAIL_SMTP_FROM | My Site <[email protected]> | 可选的默认发件人 |
EMAIL_SMTP_FROM_NAME | My Site | EMAIL_SMTP_FROM_EMAIL 的可选显示名称 |
EMAIL_SMTP_FROM_EMAIL | [email protected] | 可选的发件人地址;优先于 EMAIL_SMTP_FROM |
EMAIL_SMTP_REPLY_TO | [email protected] | 可选的 Reply-To 地址 |
如果没有设置发件人变量,EmDash 会使用 EMAIL_SMTP_USER 作为发件人。如果您的 SMTP 登录名不是电子邮件地址,请设置 EMAIL_SMTP_FROM_EMAIL 或 EMAIL_SMTP_FROM,否则投递会失败并提示 Invalid sender address for SMTP delivery。在这种情况下,Settings → Email 会在保存前要求填写发件人电子邮件。
当环境变量完整时,EmDash 会通过 SMTP 发送,除非有电子邮件提供商插件处于活动状态,或在 Settings → Email 中选择了其他提供商。若要在使用提供商插件的同时继续使用 SMTP,请在那里选择 SMTP 并保存。
在 Cloudflare Workers 上,该传输需要 nodejs_compat 兼容性标志。请参阅 Cloudflare 部署指南。
生产环境:安装提供商插件
Cloudflare Workers
在 Cloudflare 上,使用 @emdash-cms/cloudflare/plugins 中的 cloudflareEmail() 插件。它通过 Worker send_email 绑定通过 Cloudflare Email Sending 发送,因此不需要外部帐户或 API 密钥。Cloudflare 部署指南将指导您完成发件人域的注册、添加绑定和注册插件。
Node 和其他平台
社区维护的 emdash-smtp 插件系列涵盖通用 SMTP 加托管提供商,包括 Amazon SES、Brevo、Mailgun、Postmark、Resend、SendGrid、Zoho 等。
pnpm add emdash-smtp
以下配置将插件注册到 EmDash:
import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { emdashSmtp } from "emdash-smtp";
export default defineConfig({
integrations: [
emdash({
// ...您的数据库/存储配置
plugins: [emdashSmtp()],
}),
],
});
提供商凭据通过插件自己的设置进行配置 — 有关提供商矩阵和设置详细信息,请参阅其 README。
提供商凭据的存储位置
提供商插件将其 API 密钥和密码声明为插件设置。在管理面板的插件设置页面中输入它们;EmDash 将它们与其他插件设置一起存储在数据库中,轮换密钥意味着在那里粘贴新值。Secrets & Key Management 描述了存储及其注意事项。
插件是否可以读取部署机密(wrangler secret put、.env)取决于其格式,因此请遵循其 README。沙箱插件无法访问 process.env 或平台绑定。原生插件可以读取 process.env;它不得使用 import.meta.env,后者在构建时内联并将构建机器的值烘焙到包中。
选择提供商并测试
-
安装并激活提供商插件,然后在管理面板中打开 Settings → Email。
-
如果安装了多个提供商插件,请在那里选择活动的一个 — 一次只有一个传递。
-
使用 Send test email 端到端验证完整管道。结果直接显示传递错误,这是调试凭据的最快方法。
故障排除
- “No email provider is configured”:没有活动的提供商。配置 SMTP 或激活提供商插件,然后在 Settings → Email 中选择它。
- 魔法链接/邀请悄然不可用 — 相同原因。没有提供商,用户页面仍会创建邀请,但您必须手动复制邀请链接。
- 在开发环境中有效,在生产环境中失败 — 开发环境使用内置控制台提供商,掩盖了缺少的生产提供商。在部署的站点上检查 Settings → Email。
- 电子邮件进入垃圾邮件 — 在您的电子邮件提供商处为您的发送域配置 SPF/DKIM/DMARC;这是提供商端的,不是 EmDash 设置。