预览	主题	样式特点
	Horizon	蓝色强调色、灰色文字、居中白色卡片
	Terminal	深色背景、等宽字体、绿色强调色
	Ember	暖橙色调、衬线标题、圆角按钮
	Bloom	浅蓝色渐变、圆角卡片与按钮
	Heritage	藏蓝与金色、双线边框、衬线字体
	Neon	深色背景、粉红与青色、发光效果
	Mono	黑白配色、红色强调色、直角边框
	Terra	大地色调、陶土色按钮、衬线字体
	Ink	报刊式布局、侧栏、衬线字体与首字下沉
	Aurora	深紫色背景、青绿色强调色、柔和光晕

截图展示当前源码的构建结果。其他邮件类型和语言可通过本地预览查看；更新截图请参阅截图指南。

安装

选择安装来源

运行 gitea --version 确认实例版本，再按兼容矩阵选择模板版本。

来源	邮件模板目录	准备步骤
发行压缩包	`themes/<名称>/mail/`	下载并解压推荐版本的发行包
源码仓库	`build/themes/<名称>/mail/`	使用 Go 1.24 或更高版本构建

从源码构建时，在仓库根目录执行：

cd tools
go run . build all
cd ..

缓存不存在时，首次构建会下载 gitea.lock.json 锁定的官方文件；后续构建会先校验缓存。构建需要根目录的锁文件，文件缺失或缓存损坏的处理方式见准备与恢复说明。

安装主题

将所选主题 mail/ 目录中的内容复制到 <GITEA_CUSTOM>/templates/mail/，然后重启 Gitea。复制前请确认实例实际使用的自定义目录。以下是常见部署路径示例：

部署方式	自定义目录示例
Linux 二进制部署	`/var/lib/gitea/custom`
Docker	`/data/gitea`
Windows	`C:\gitea\custom`

例如，在使用 systemd 管理 Gitea 的 Linux 主机上，从已解压的发行包目录执行：

mkdir -p /var/lib/gitea/custom/templates/mail
cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
systemctl restart gitea

使用源码构建产物时，将复制来源改为 build/themes/horizon/mail/.。Docker 和 Windows 部署请使用相应的容器或服务管理方式重启。

切换主题

先备份已有邮件模板，再移除上一主题安装的文件，复制新主题的完整产物。当前源码构建会在 build.json 中记录生成的文件；历史发行包可参照压缩包内容确认文件范围。保留其他自定义模板。

从 framed 切换到 shared 模式时，尤其需要清理旧主题文件，否则残留的覆盖模板可能继续使用原有布局。

确认生效

使用测试账户触发密码重置等邮件通知，检查邮件样式和链接。管理后台的测试邮件按钮不使用自定义邮件模板。

预览

预览支持切换主题、邮件类型和语言，查看渲染结果或 HTML 源码，切换桌面与移动端视口，以及查看示例数据面板。v28.0.0 快照包含 11 种邮件类型和 28 种语言。

静态预览

在源码仓库中生成预览数据：

cd tools
go run . preview all
cd ..

在浏览器中打开 preview/index.html。语言数据按需加载，支持 file://，无需启动服务器。当前打包脚本生成的发行包包含这些数据；历史发行包保留其原有预览内容。

开发服务器

cd tools
go run . dev

打开 http://127.0.0.1:3456。Go 服务器监听主题文件、共享框架、锁文件与缓存、预览测试数据的变化，重新构建后通过服务器发送事件（SSE）刷新页面。

控件	选项或快捷键
主题、模板、语言和视图	`←` / `→` 切换选择框，`↑` / `↓` 选择选项
视图	Modern 显示渲染结果，Source 显示生成的 HTML 文本
视口	Desktop（1386 × 780）、Mobile（390 × 780）；快捷键 `d` / `m`
信息面板	`p` 展开或收起面板

预览使用示例数据渲染模板。浏览器与邮件客户端对 CSS 的支持不同，部署前还需在目标邮件客户端中检查效果。

兼容性

最新测试： Gitea 28.0.0

最新发布版： v28.0.0

上游 Gitea 28.1.0： [PENDING]

当前源码架构面向 Gitea 28 及更高版本，兼容性按锁定版本验证。新的上游版本在完成评审前保持待验证状态。早期 Gitea 版本请使用兼容矩阵推荐的发行包；其中也记录了 v1.27.2 推送通知修复不完整的问题。

生成的模板使用 Gitea 内置函数和官方翻译键，缺少的翻译回退为英文。锁定的 v28.0.0 语言文件存在已知的波兰语邀请文案格式缺陷，预览会报告 [UPSTREAM-WARN] 并保留官方输出。详见已知限制。

目录结构

gitea.lock.json        # 官方标签、提交和文件校验值
framework/            # 共享邮件控件和布局预设
themes/<名称>/        # 主题元数据（theme.json）和样式（theme.css）
tools/                # Go 命令行工具、构建工具和测试
  cli/                # 命令定义
  upstream/           # 快照下载、校验和翻译键发现
  builder/            # 官方模板适配与主题生成
  preview/            # 邮件渲染、语言适配和开发服务器
  config/, data/      # 预览元数据和示例上下文
  integration/, qa/   # 可选的 Gitea 实例与浏览器检查
preview/              # 浏览器界面；生成的清单和语言数据包
docs/                 # 简体中文指南和画廊图片
.github/              # 工作流、发行说明、打包与版本追踪脚本
build/upstream/       # 下载的官方文件，不纳入版本控制
build/themes/         # 生成的安装模板，不纳入版本控制

官方模板定义通知数据、条件、主题行和 URL。共享框架将其组织为页头、操作按钮、备用链接和页脚，主题定义配色、字体与间距。framed 和 shared 模式的说明见主题开发指南。

模板类型

邮件类型从锁定的快照中发现。v28.0.0 的邮件入口如下：

文件	通知类型
`mail/user/auth/activate.tmpl`	账户激活
`mail/user/auth/activate_email.tmpl`	邮箱验证
`mail/user/auth/register_notify.tmpl`	注册通知
`mail/user/auth/reset_passwd.tmpl`	密码重置
`mail/org/team_invite.tmpl`	团队邀请
`mail/repo/collaborator.tmpl`	添加仓库协作者
`mail/repo/transfer.tmpl`	仓库所有权转移
`mail/repo/release.tmpl`	发布新版本
`mail/repo/actions/workflow_run.tmpl`	Actions 工作流运行
`mail/repo/issue/assigned.tmpl`	议题或合并请求指派
`mail/repo/issue/default.tmpl`	议题或合并请求动态

参与贡献

欢迎改进主题、工具、文档和翻译。贡献指南介绍了本地环境准备、设计规范、检查要求和发布流程。

许可证

本项目采用 MIT 许可证。生成的发行包保留 Gitea 许可证和快照来源信息，详见第三方声明。

本项目与 Gitea 官方无隶属关系。

README.zh-CN.md Unescape Escape

Gitea 邮件模板

风格画廊

安装