超简单！React-Email 零基础 Windows 安装与实战指南

樊会灿

371人浏览 · 2025-09-11 06:31:29

樊会灿 · 2025-09-11 06:31:29 发布

超简单！React-Email 零基础 Windows 安装与实战指南

【免费下载链接】react-email 💌 Build and send emails using React 项目地址: https://gitcode.com/GitHub_Trending/re/react-email

你还在为 HTML 邮件排版错乱抓狂？还在忍受复杂的表格布局和客户端兼容性问题？本文将带你零基础上手 React-Email，用 React 组件轻松搞定邮件开发，10 分钟搭建可视化编辑环境，让你的邮件开发效率提升 300%！

读完本文你将学会：

在 Windows 系统快速部署 React-Email 开发环境
使用 CLI 工具创建和预览动态邮件模板
掌握组件化邮件开发的核心技巧
解决常见的 Windows 平台兼容性问题

准备工作：环境配置

在开始之前，请确保你的 Windows 系统已安装以下工具：

Node.js (v16.0.0 或更高版本)：官方下载地址
Git：国内镜像下载
代码编辑器（推荐 VS Code）：下载地址

安装 Node.js 的注意事项

Windows 用户安装 Node.js 时，请勾选 "Add to PATH" 选项，这样可以在命令提示符中直接使用 node 和 npm 命令。安装完成后，打开 PowerShell 验证版本：

node -v
npm -v

如果出现版本号，则说明安装成功。如果提示 "命令未找到"，请检查环境变量配置或重新安装 Node.js。

两种安装方式：自动 vs 手动

React-Email 提供了两种安装方式，你可以根据自己的需求选择：

方式一：自动安装（推荐新手）

使用官方提供的 create-email 工具，一键创建完整项目：

npx create-email@latest

根据提示输入项目名称（如 my-email-project），选择模板，等待安装完成。进入项目目录并启动开发服务器：

cd my-email-project
npm run dev

方式二：手动安装（适合定制化需求）

如果你需要更灵活的项目结构，可以手动创建项目：

# 创建项目目录
mkdir react-email-starter
cd react-email-starter

# 初始化 npm 项目
npm init -y

# 安装核心依赖
npm install react-email -D -E
npm install @react-email/components react react-dom -E

编辑 package.json 文件，添加开发脚本：

{
  "scripts": {
    "dev": "email dev"
  }
}

开发环境预览

启动开发服务器后，访问 http://localhost:3000 即可看到邮件模板预览界面。修改邮件文件后，预览会实时更新，无需手动刷新。

开发服务器支持以下自定义配置：

# 更改邮件模板目录
npm run dev -- --dir=src/emails

# 更改端口号
npm run dev -- --port=4000

创建第一个邮件模板

在项目根目录下创建 emails 文件夹，新建 welcome-email.tsx 文件：

import { Button, Html, Text, Head, Preview } from "@react-email/components";
import * as React from "react";

export default function WelcomeEmail() {
  return (
    <Html>
      <Head>
        <title>欢迎使用 React-Email</title>
      </Head>
      <Preview>这是一封使用 React-Email 创建的欢迎邮件</Preview>
      <Text>亲爱的用户：</Text>
      <Text>
        感谢您选择 React-Email！使用 React 组件构建邮件从未如此简单。
      </Text>
      <Button
        href="https://react-email-demo.com"
        style={{ background: "#0070f3", color: "white", padding: "12px 24px" }}
      >
        查看示例
      </Button>
    </Html>
  );
}

// 预览模式下的默认 props
WelcomeEmail.PreviewProps = {
  username: "新用户"
};

React-Email 提供了丰富的内置组件，完整列表可查看官方组件文档。

常用 CLI 命令

React-Email 提供了强大的命令行工具，帮助你高效开发：

命令	功能描述
`email dev`	启动开发服务器，实时预览邮件
`email build`	构建生产环境版本
`email export`	导出静态 HTML 文件
`email help`	查看命令帮助

导出静态 HTML 文件：

# 导出所有邮件模板到 out 目录
npx email export

# 自定义输出目录
npx email export --outDir=dist/emails

Windows 常见问题解决

1. 路径中文乱码问题

如果邮件模板中包含中文，可能会出现乱码。解决方法：在 emails 目录下创建 static 文件夹，将字体文件放入其中，在邮件中引用：

import { Font } from "@react-email/components";

export default function ChineseEmail() {
  return (
    <Html>
      <Font
        fontFamily="SimSun"
        src="static/simsun.ttf"
      />
      <Text style={{ fontFamily: "SimSun" }}>中文内容显示正常了</Text>
    </Html>
  );
}

2. 端口被占用问题

如果 3000 端口被占用，可以指定其他端口启动：

npm run dev -- --port=3001

3. 依赖安装缓慢

Windows 用户可以使用淘宝 npm 镜像加速依赖安装：

npm config set registry https://registry.npmmirror.com

部署与发送邮件

React-Email 支持多种邮件发送方式，以下是使用 Nodemailer 的示例：

import { render } from "@react-email/render";
import nodemailer from "nodemailer";
import WelcomeEmail from "./emails/welcome-email";

async function sendEmail() {
  const transporter = nodemailer.createTransport({
    host: "smtp.example.com",
    port: 587,
    secure: false,
    auth: {
      user: "your-email@example.com",
      pass: "your-password"
    }
  });

  const emailHtml = render(<WelcomeEmail />);
  
  await transporter.sendMail({
    from: "your-email@example.com",
    to: "recipient@example.com",
    subject: "欢迎邮件",
    html: emailHtml
  });
}

sendEmail();

更多集成方式请参考集成文档。