模板开发流程
最后更新:2026-11-04
面向模板开发者:从零做一套前台模板,到打包交付、客户在后台一键切换的完整流程。每一步都对应本手册后续章节,可按需展开。
全流程一览
准备目录结构 → 读基模板(21 个页面文件)→ 覆盖你想改的页面
→ 用标签取数(list / one / pagebar)→ 处理多语言与 SEO
→ 引用资源(/templates/<模板名>/…)→ 上传图片规范
→ 打包成自包含文件夹 → 客户放进 templates/ 后台选 → 保存即生效
第 1 步:目录结构(文件夹名 = 模板名)
templates/
└── mytheme/ ← 文件夹名 = 模板名 = tpl_path
├── index.html ← 首页(.html 必须放在根层!)
├── header.html ← 公共头部
├── footer.html ← 公共底部
├── news.html ← 文章列表
├── news_detail.html ← 文章详情
├── products.html / product_detail.html
├── cases.html / case_detail.html
├── category.html ← 栏目页
├── page_detail.html ← 单页
├── about.html / contact.html / error.html / icons.html
├── css/ js/ images/ ← 子目录只能放资源,不能放 .html
四条硬约束
| # | 约束 | 违反后果 |
|---|---|---|
| 1 | 所有 .html 必须在模板文件夹根层 |
系统用 ParseGlob(templates/<模板名>/*.html) 加载,不递归子目录,放进 pages/ 的文件不会被加载 |
| 2 | 根层至少要有一个 .html |
否则不会出现在后台下拉框(只装了子目录的文件夹会被自动跳过) |
| 3 | index 与 admin 是保留名 |
templates/index/ 是基模板、templates/admin/ 是后台界面,不可用作模板名 |
| 4 | 资源必须用 /templates/<模板名>/… 绝对路径 |
相对路径在详情页等多级 URL 下会解析错误 |
第 2 步:理解「基模板 + 覆盖层」
渲染时先加载基模板 templates/index/,再用你的模板文件夹覆盖同名文件。所以模板包不必包含全部页面——没提供的自动沿用基模板。
| 你的包里有 | 实际渲染结果 |
|---|---|
index.html + header.html + footer.html |
首页、头尾用你的;其余页面用基模板(但会带上你的头尾) |
| 全部 21 个页面文件 | 完全由你的模板接管 |
只有 index.html |
只有首页是你的样式,其它页面保持基模板外观 |
基模板包含的 21 个页面文件(可覆盖清单)
index.html header.html footer.html icons.html news.html
news_detail.html products.html product_detail.html cases.html case_detail.html
category.html page_detail.html about.html contact.html error.html
tag.html jobs.html job_detail.html search.html languages.html
media_gallery.html
建议:做完整交付时至少覆盖
index.html、header.html、footer.html以及各列表/详情页,避免风格割裂。
第 3 步:取数标签
模板内通过 {{.字段名}} 读取后台数据,通过 list / one 等函数灵活取数。
| 需求 | 用哪个 | 对应章节 |
|---|---|---|
| 任意条件查询内容 | list |
内容列表 |
| 取指定一条内容 | one |
指定内容(one 函数) |
| 分页条 | pagebar |
分页条 |
| 多值字段(多图 / tags / 多选) | splitJSON |
内容多图遍历 / tags / 多选遍历 |
| 当前栏目 / 指定栏目 | .CurrentCategory 等 |
当前栏目 / 指定栏目 |
| 导航菜单 | 站点导航数据 | 导航菜单 |
| 轮播图 | 幻灯片数据 | 幻灯片轮播 |
| 面包屑 | 父级栏目 + 当前栏目 | 面包屑专题演示 |
| 站内全文搜索 | 搜索页数据 | 站内全文搜索 |
| 多语言互链 | {{.LangSwitcher}} / {{.HrefLangs}} |
多语言建站 |
| 公司 / 站点信息 | 公司信息 / 站点信息 | 对应章节 |
| 友情链接 | 友链数据 | 友情链接 |
管道与常用函数
| 用途 | 写法 | 说明 |
|---|---|---|
| 日期格式化 | {{.CreatedAt \| formatDate "Y-m-d"}} |
按格式输出时间 |
| 内容截取 | {{.Summary \| truncate 50}} |
按字符(rune)截取,中文友好,超出补 ... |
| 原样输出 HTML | {{.Content \| safeHTML}} |
富文本默认转义,标记为安全 HTML 后原样渲染 |
| 数值运算 | {{add .CurrentPage 1}} |
整数相加 |
| JSON / 多值拆分 | {{range splitJSON .Images}} |
多图、tags 等解析为可遍历切片 |
| 自定义片段 | {{.FooterNotice}} |
后台「模板内容片段」以同名全局变量注入(名称由你在后台定义) |
详情链接必须用 {{.URL}}——它自带站点前缀,多语言子站才正确;写死 /news/{{.ID}} 会丢语言前缀。
第 4 步:资源引用
模板文件夹里的 css/js/图片通过专用静态路由伺服,URL 规则为 /templates/<模板名>/<相对路径>:
<link rel="stylesheet" href="/templates/mytheme/css/style.css">
<script src="/templates/mytheme/js/main.js"></script>
<img src="/templates/mytheme/images/logo.png" alt="logo">
也兼容全站共享的 /static/…。自包含模板推荐一律走 /templates/<模板名>/,整包拷走即可复用。
允许的资源扩展名(前台可引用)
| 类别 | 扩展名 |
|---|---|
| 样式 / 脚本 | .css .js .mjs |
| 图片 | .png .jpg .jpeg .gif .svg .webp .bmp .ico .avif |
| 字体 | .woff .woff2 .ttf .eot .otf |
| 音视频 | .mp4 .webm .ogg .mp3 .wav |
| 数据 / 文档 | .json .xml .txt .csv .pdf |
.html及任何非白名单扩展名通过 URL 访问返回 403,模板源码不会被下载;../路径穿越同样被拦截。所以把.html和资源放在同一文件夹是安全的。
第 5 步:上传图片规范
后台「上传图片」比前台资源引用更严格,仅允许 .jpg .jpeg .png .gif .webp .avif:
.svg(有 XSS 风险)与.bmp已从上传白名单移除,无法经后台上传(但仍可作为静态资源手动放入引用);- 上传的图片会在浏览器端自动压缩并转换为 AVIF(不支持则 WebP)后再提交;
- 服务端会做真实类型校验兜底,不信任扩展名。
完整机制见《后台上传图片:安全校验与自动转 AVIF》。
第 6 步:多语言与 SEO
- 多语言是「一语言 = 一个站点」,路径前缀(如
/en)由站点解析器自动剥离与处理; - 用「站点管理 → 一键启用语言站点」批量建站时,每个语言站会拿到一份中文站当前模板的完整副本(多租户落在
<租户目录>/templates/<语言码>/),各语言模板互不影响;模板里硬编码的中文文案仍需逐语言修改; - 语言切换器用
{{.LangSwitcher}},hreflang 互链用{{.HrefLangs}}; - SEO 头部需要接的变量:
{{.PageTitle}}/{{.PageKeywords}}/{{.PageDescription}},另有 canonical、og、JSON-LD 相关变量; - 详情页自动输出 Article / Product JSON-LD 与面包屑 BreadcrumbList。
多语言标签是否输出,取决于当前站点是否拥有多语言能力:SaaS 下由平台按套餐/订阅判定,独立交付版下由授权码判定。详见《授权与邮件服务》开头的适用范围说明。
第 7 步:打包与交付
| 角色 | 要做的事 |
|---|---|
| 模板开发者(你) | 做好一整套模板,所有文件放在一个文件夹里,交付该文件夹 |
| 部署 / 运维 | 把文件夹整个放进程序目录的 templates/ 下 |
| 客户 | 后台「站点信息 → 模板路径」下拉里选中它 → 保存。立即生效 |
多语言站点可以各选不同模板:每个站点(含子站)在「站点管理」里独立设置自己的模板路径。用「一键启用语言站点」创建的语言站,其模板是中文站模板的副本,修改该副本只影响这一门语言,不会动到其它语言或共享模板。
第 8 步:安装与切换
| 步骤 | 操作 |
|---|---|
| 1 | 把模板文件夹整个复制进程序所在目录的 templates/ 下 |
| 2 | 后台 →「站点信息」→「模板路径」下拉,选中它 |
| 3 | 点击保存。系统自动重新加载模板,无需重启进程 |
| 4 | 刷新前台查看效果(若开了页面缓存,等约 1 分钟或在后台清理缓存) |
第 9 步:后台扩展与运维(模板开发者也该知道)
模板最终跑在 CMS 上,这些后台能力会直接影响前台输出:
| 能力 | 入口 / 说明 |
|---|---|
| 外部事件 Webhook | 内容创建/更新/删除推送到外部系统;CMS_WEBHOOK_URLS + CMS_WEBHOOK_EVENTS 配置后启用 |
| 钩子总线 | 进程内事件总线(internal/hooks),可注册自定义钩子与自定义路由 |
| 自定义模板函数 | 在 GetTemplateFuncs 中注册后前台可用(模板里不能调用未注册的函数名) |
| 媒体库 | /admin/media,列出 static/uploads/ 全部文件,支持重命名 / 删除 / 未使用清理 |
| 备份与恢复 | /admin/backup,JSON 导出导入 + SQLite 整库快照 |
| 审计日志 | /admin/audit,记录登录、内容增删改、媒体删除、备份恢复 |
| 批量增加 / 删除 | 五类内容均支持批量添加(含「快速导入」)与批量删除 |
| 翻译状态核查 | /admin/i18n,列出目标站点缺失或标题为空的待翻译项 |
| 静态空间发布 | /admin/deploy,8 类空间 + 按文件类别拆分 + 连通测试 |
| 配置参数 | /admin/config,8 个分组;其中 URL 规则 / 标题样式直接决定 {{.URL}} 与 {{.PageTitle}} |
| WebAPI | 对外只读 JSON 接口(仅 GET,只返回已发布内容),开关与令牌在配置参数里 |
| 搜索引擎主动推送 | 百度接口 / IndexNow,可开「保存后自动推送」 |
| 安全配置 | 登录失败锁定、后台 IP 白名单、会话策略、上传黑名单 |
| 系统更新 | /admin/system-update,运行时信息 + 清日志 / 整理数据库 |
第 10 步:交付前自检清单
| 检查项 | 标准 |
|---|---|
所有 .html 在文件夹根层 |
子目录里没有 .html |
| 资源全部用绝对路径 | 搜一遍确认没有 href="css/、src="images/ 这类相对写法 |
| 模板名与资源路径一致 | 文件夹叫 mytheme,引用就必须是 /templates/mytheme/… |
详情链接用 {{.URL}} |
没有写死 /news/{{.ID}} 等 |
| SEO 变量已接 | {{.PageTitle}} / {{.PageKeywords}} / {{.PageDescription}} |
| 头尾复用 | 用 {{template "header.html" .}} 而非各页复制粘贴 |
| 没有多余大文件 | 清掉设计稿、.psd、node_modules 等(也无法被伺服) |
常见问题排查
| 现象 | 原因与解决 |
|---|---|
| 下拉框里看不到我的模板 | 根层没有 .html;或用了保留名 index / admin;或没放进程序目录的 templates/ |
| 选了模板但页面没变化 | .html 放进了子目录(不被加载);或文件名与基模板不一致导致没覆盖;或页面缓存未过期 |
| 结构对了但没样式、图片裂开 | 资源路径写错。必须是 /templates/<模板名>/css/style.css,不能相对路径,也不能漏开头的 / |
| 某个资源返回 403 | 扩展名不在白名单内(尤其直接访问 .html 是刻意禁止的) |
| 某个资源返回 404 | URL 路径与磁盘实际路径不一致(注意大小写);或文件确实不存在 |
| 多语言子站链接丢了语言前缀 | 详情链接写死了 /news/{{.ID}},必须改用 {{.URL}} |
改了 .html 但前台还是旧的 |
模板在启动/保存站点时加载。改文件后到后台重新保存一次站点信息即可触发重载 |
相关文档:CMS 后台操作流程 · 静态站发布 · 多语言建站
云建站 SaaS