📦 模板打包规范(自包含模板包)

最后更新:2026-11-04

本章面向模板开发者:如何把一套网站模板(HTML + 图片 + CSS + JS)打包成一个自包含文件夹,放进 templates/ 后,客户即可在后台「站点信息 → 模板路径」下拉框里直接选用,保存即生效、无需重启、无需改代码。

🎯 交付模型

角色 要做的事
模板开发者(你) 做好一整套模板,所有文件放在一个文件夹里,交付该文件夹
部署 / 运维 把文件夹整个放进程序目录的 templates/ 下
客户 后台「站点信息 → 模板路径」下拉里选中它 → 保存。立即生效

多语言站点可以各选不同模板:每个站点(含子站)在「站点管理」里独立设置自己的模板路径。用「一键启用语言站点」创建的语言站会自带一份中文站模板的副本,改它只影响该语言。

📁 推荐目录结构

以模板名 mytheme 为例。文件夹名就是模板名,也是后台下拉里显示的名字,同时是资源 URL 的路径段。

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/                  ← 子目录只能放资源,不能放 .html
    │   └── style.css
    ├── js/
    │   └── main.js
    └── images/
        ├── logo.png
        └── banner.jpg

⚠️ 四条硬约束(务必遵守)

1. 所有 .html 必须放在模板文件夹的根层

系统用 ParseGlob(templates/<模板名>/*.html) 加载模板,不递归子目录。放进 mytheme/pages/about.html 的文件不会被加载。子目录只用来放 css/js/图片等资源。

2. 文件夹里至少要有一个 .html,否则不会出现在下拉框

后台下拉只列出「真正的模板包」。一个只装了子目录、根层没有 .html 的文件夹会被自动跳过(否则选中后会静默退回默认模板,表现为「选了没反应」)。

3. 保留名不可用:index 与 admin

templates/index/ 是基模板(兜底层),templates/admin/ 是后台界面模板。这两个名字被系统占用,不会出现在客户的选择列表里,也不要用作你的模板名。

4. 资源必须用 /templates/<模板名>/… 绝对路径引用

见下一节。用相对路径(如 css/style.css)在详情页等多级 URL 下会解析错误。

🔗 资源引用约定

模板文件夹里的 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">

<!-- CSS 内部可用相对路径(相对该 css 文件所在目录) -->
<!-- background: url(../images/banner.jpg); -->

也可以继续使用全站共享的 /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
⚠️ 注意

上传与引用是两回事:上表是前台可引用的静态资源扩展名。后台「上传图片」受更严格限制,仅允许 .jpg .jpeg .png .gif .webp .avif;.svg(有 XSS 风险)与 .bmp 已从上传白名单移除,无法经后台上传(但仍可作为静态资源手动放入 /static/ 引用)。上传的图片会在浏览器端自动压缩并转换为 AVIF(不支持则 WebP)后再提交,且服务端会做真实类型校验兜底——完整机制见 上传图片安全与转 AVIF 一章。

安全说明:.html 及任何非白名单扩展名通过 URL 访问会返回 403,模板源码不会被下载;../ 路径穿越同样被拦截。所以把 .html 和资源放在同一文件夹是安全的。

🧱 叠加机制:只需覆盖你想改的文件

渲染时先加载基模板 templates/index/,再用你的模板文件夹覆盖同名文件。所以模板包不必包含全部页面——没提供的页面自动沿用基模板。

你的包里有 实际渲染结果
index.html + header.html + footer.html 首页、头尾用你的;其余页面用基模板(但会带上你的头尾)
全部 21 个页面文件 完全由你的模板接管
只有 index.html 只有首页是你的样式,其它页面保持基模板外观

建议:做完整交付时至少覆盖 index.html、header.html、footer.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

🚀 最小可用模板包示例

一个只改首页样式的最小包,三个文件即可跑通。

<!-- templates/mytheme/index.html -->
<!DOCTYPE html>
<html lang="{{.SiteLanguage}}">
<head>
  <meta charset="UTF-8">
  <title>{{.PageTitle}}</title>
  <meta name="keywords" content="{{.PageKeywords}}">
  <meta name="description" content="{{.PageDescription}}">
  <link rel="stylesheet" href="/templates/mytheme/css/style.css">
</head>
<body>
  {{template "header.html" .}}

  <img src="/templates/mytheme/images/logo.png" alt="{{.SiteTitle}}">

  <ul class="news-list">
  {{range list "type=news&num=8&order=date"}}
    <li>
      <a href="{{.URL}}">{{.Title}}</a>
      <time>{{.CreatedAt | formatDate "Y-m-d"}}</time>
    </li>
  {{end}}
  </ul>

  {{template "footer.html" .}}
  <script src="/templates/mytheme/js/main.js"></script>
</body>
</html>

注意示例里的两个要点:详情链接必须用 {{.URL}}(自带站点前缀,多语言子站才正确),资源用 /templates/mytheme/… 绝对路径。

📥 安装与切换步骤

步骤 操作
1 把模板文件夹(如 mytheme/)整个复制进程序所在目录的 templates/ 下
2 后台 →「站点信息」→「模板路径」下拉,选中 mytheme
3 点击保存。系统自动重新加载模板,无需重启进程
4 刷新前台查看效果(若开启了页面缓存,可等约 1 分钟或在后台清理缓存)

多站点场景:在「站点管理」里为每个站点分别选择模板路径,各语言站可用不同模板;一键启用的语言站默认已有独立模板目录,无需再手工复制。

🔍 常见问题排查

现象 原因与解决
下拉框里看不到我的模板 文件夹根层没有任何 .html;或用了保留名 index/admin;或没放进程序目录的 templates/
选了模板但页面没变化 你的 .html 放进了子目录(不被加载,必须在根层);或文件名与基模板不一致导致没有覆盖;或页面缓存未过期
页面结构对了但没样式、图片裂开 资源路径写错。必须是 /templates/<模板名>/css/style.css,不能用相对路径,也不要漏掉开头的 /
某个资源返回 403 扩展名不在白名单内(尤其是想直接访问 .html——这是刻意禁止的)
某个资源返回 404 URL 路径与磁盘实际路径不一致(注意大小写);或文件确实不存在
多语言子站链接丢了语言前缀 详情链接写死了 /news/{{.ID}}。必须改用 {{.URL}}
改了 .html 但前台还是旧的 模板在启动/保存站点时加载。改文件后到后台重新保存一次站点信息即可触发重载

✅ 交付前自检清单

检查项 标准
所有 .html 在文件夹根层 子目录里没有 .html
资源全部用绝对路径 搜一遍确认没有 href="css/、src="images/ 这类相对写法
模板名与资源路径一致 文件夹叫 mytheme,引用就必须是 /templates/mytheme/…
详情链接用 {{.URL}} 没有写死 /news/{{.ID}} 等
SEO 变量已接 {{.PageTitle}} / {{.PageKeywords}} / {{.PageDescription}}
头尾复用 用 {{template "header.html" .}} 而非各页复制粘贴
没有多余大文件 清掉设计稿、.psd、node_modules 等(也无法被伺服)
[← 多语言建站](18-multilang.html) [上传图片规范 →](20-upload.html)
本网站使用 Cookie 以保障基本功能与改善体验。详情见隐私政策。