模板开发流程

最后更新: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 后台操作流程 · 静态站发布 · 多语言建站

本网站使用 Cookie 以保障基本功能与改善体验。详情见隐私政策。