10 主题与 SSR

欢迎加入 插件 / 主题制作团队：QQ 群入口（后台「主题模板」页亦有同款按钮）。

三套主题类型

内部 type	魔方目录	用途
`home`	`public/themes/web/`	官网首页
`clientarea`	`public/themes/clientarea/`	会员中心
`cart`	`public/themes/cart/`	购物车

内置皮肤名：default、cloud、classic（各 type 独立配置）

SPA 模式（默认）

前台 Vue 通过 siteConfig API 获取：

json

{
  "theme": { "home": "cloud", "clientarea": "default", "cart": "default" },
  "theme_assets": { "home": { "css": [...], "js": [...] } },
  "theme_config": { "home": { "hero-from": "#0052d9" } }
}

动态注入 CSS 变量与外链样式，无需改 Vue 源码。

.tpl SSR 模式

适用于魔方 legacy 主题或需要服务端渲染 HTML 的场景。

开启

后台 API：POST /admin/theme/ssrMode body: { "mode": "tpl" }
或写入配置 theme.ssr_mode = tpl

访问

URL	说明
`/tpl/home`	渲染 home 主题 index.tpl
`/tpl/cart`	购物车模板
`/home/theme_tpl/render?type=home&page=index`	API 返回 HTML 或 JSON
`/home/theme_tpl/page?path=home`	`/tpl/*` 美化路由的实际转发目标

控制器为 app\home\controller\ThemeTpl，URL 段为 theme_tpl（不是 theme，后者是后台主题管理控制器）。

/tpl/* 在两端都已打通：

开发：public/router.php 将 /tpl/{path} 转发到 /home/theme_tpl/page?path={path}
生产：deploy/nginx-baota.conf 含对应 location ~* ^/tpl(/|$) 伪静态

当激活的是 Vue SPA 主题（未开启 .tpl SSR）时，/tpl/* 会 302 跳回前台 SPA 根路径 /，属正常行为。

模板语法（Smarty 子集）

实现类：app/common/helper/ThemeTplRenderer

语法	示例
变量	`{$site.site_name}`、`{$page_title\|escape}`
包含	`{include file="partials/header.tpl"}`
条件	`{if $site.seo_desc}...{/if}`
循环	`{foreach $nav as $item}...{/foreach}`
字面量	`{literal}...{/literal}`
注释	`{* 注释 *}`

默认注入变量：site、theme_config、theme_assets、year

手把手教程：请先读 10a 主题开发详细教程。文档配套示例主题源码：frontend/themes/starter/（构建后输出到 public/themes/）。

开发主题

仅 CSS（推荐 SPA）

public/themes/web/mytheme/theme.css

或 theme.json：

json

{
  "title": "我的主题",
  "assets": {
    "css": ["theme.css"],
    "js": []
  }
}

含 .tpl（SSR）

public/themes/web/mytheme/
  index.tpl
  partials/header.tpl
  theme.css

后台 主题管理 → 扫描 同步到 kd_themes 表。

10 主题与 SSR ​

三套主题类型 ​

SPA 模式（默认） ​

.tpl SSR 模式 ​

开启 ​

访问 ​

模板语法（Smarty 子集） ​

开发主题 ​

仅 CSS（推荐 SPA） ​

含 .tpl（SSR） ​

相关 API ​