c6a3ad5332
- 修正From字段配置，确保邮箱地址与SMTP认证用户一致 - 添加fromName支持，支持自定义发件人显示名称 - 改进From字段格式化，符合RFC5322标准 - 添加配置验证，防止空邮箱地址错误 - 创建QQ邮箱配置指南和测试demo 解决550 From header错误，完善邮件服务
104 lines
2.7 KiB
Markdown
104 lines
2.7 KiB
Markdown
# QQ邮箱配置指南
|
||
|
||
## 🚨 问题原因
|
||
错误 `550 The "From" header is missing or invalid` 是因为QQ邮箱要求：
|
||
1. **From字段的邮箱地址必须与SMTP认证用户名完全一致**
|
||
2. **From字段格式必须符合RFC5322标准**
|
||
|
||
## ⚙️ 正确配置步骤
|
||
|
||
### 第一步：获取QQ邮箱授权码
|
||
|
||
1. 登录 [QQ邮箱网页版](https://mail.qq.com/)
|
||
2. 点击右上角 **设置** → **账户**
|
||
3. 找到 **"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"**
|
||
4. 开启 **"IMAP/SMTP服务"**
|
||
5. 按提示发送短信验证
|
||
6. 获得16位授权码（例如：`abcdefghijklmnop`）
|
||
|
||
### 第二步：创建.env文件
|
||
|
||
在项目根目录创建 `.env` 文件，内容如下：
|
||
|
||
```env
|
||
# QQ邮箱SMTP配置
|
||
SMTP_HOST=smtp.qq.com
|
||
SMTP_PORT=587
|
||
SMTP_SECURE=false
|
||
|
||
# 认证信息（重要：必须使用相同的邮箱地址）
|
||
SMTP_USER=your_qq_email@qq.com
|
||
SMTP_PASS=your_16_digit_authorization_code
|
||
|
||
# 发件人信息（重要：邮箱地址必须与SMTP_USER一致）
|
||
SMTP_FROM_EMAIL=your_qq_email@qq.com
|
||
SMTP_FROM_NAME=星撰系统
|
||
|
||
# 其他配置
|
||
EMAIL_REPLY_TO=your_qq_email@qq.com
|
||
```
|
||
|
||
### 第三步：替换为你的真实信息
|
||
|
||
**示例配置：**
|
||
```env
|
||
SMTP_HOST=smtp.qq.com
|
||
SMTP_PORT=587
|
||
SMTP_SECURE=false
|
||
SMTP_USER=123456789@qq.com
|
||
SMTP_PASS=abcdefghijklmnop
|
||
SMTP_FROM_EMAIL=123456789@qq.com
|
||
SMTP_FROM_NAME=星撰系统
|
||
EMAIL_REPLY_TO=123456789@qq.com
|
||
```
|
||
|
||
## ✅ 配置要点
|
||
|
||
1. **SMTP_USER** 和 **SMTP_FROM_EMAIL** 必须是同一个QQ邮箱
|
||
2. **SMTP_PASS** 是16位授权码，不是QQ登录密码
|
||
3. **SMTP_FROM_NAME** 可以自定义，这是邮件显示的发件人名称
|
||
|
||
## 🧪 测试配置
|
||
|
||
配置完成后，运行测试：
|
||
|
||
```bash
|
||
# 快速测试
|
||
bun run quick-email-test.ts your_receive_email@example.com
|
||
|
||
# 详细测试
|
||
bun run src/tests/demo/emailDemo.ts your_receive_email@example.com
|
||
```
|
||
|
||
## 🔧 常见问题
|
||
|
||
### Q: 为什么要用授权码而不是QQ密码？
|
||
A: QQ邮箱的安全策略，第三方应用必须使用授权码
|
||
|
||
### Q: 授权码在哪里生成？
|
||
A: QQ邮箱设置 → 账户 → 开启IMAP/SMTP服务时生成
|
||
|
||
### Q: 为什么From地址必须与SMTP_USER一致？
|
||
A: QQ邮箱的反欺诈机制，防止伪造发件人
|
||
|
||
### Q: 可以使用其他邮箱服务吗？
|
||
A: 可以，修改SMTP_HOST即可：
|
||
- 163邮箱：`smtp.163.com`
|
||
- Gmail：`smtp.gmail.com`
|
||
- 企业邮箱：根据提供商配置
|
||
|
||
## 📝 配置模板
|
||
|
||
复制以下内容到 `.env` 文件：
|
||
|
||
```env
|
||
# 请替换为你的真实信息
|
||
SMTP_HOST=smtp.qq.com
|
||
SMTP_PORT=587
|
||
SMTP_SECURE=false
|
||
SMTP_USER=替换为你的QQ邮箱@qq.com
|
||
SMTP_PASS=替换为你的16位授权码
|
||
SMTP_FROM_EMAIL=替换为你的QQ邮箱@qq.com
|
||
SMTP_FROM_NAME=星撰系统
|
||
EMAIL_REPLY_TO=替换为你的QQ邮箱@qq.com
|
||
``` |