简介
本指南面向 DouPHP 的多主题资源管理，围绕“主题隔离与共享、覆盖策略、动态加载与缓存更新、公共资源复用、优先级规则、打包部署与安全”等关键主题展开。文档基于仓库中实际实现进行说明，帮助开发者高效地设计、维护与优化多主题资源体系。
项目结构
DouPHP 的前台主题位于根目录 theme 下，默认主题为 default，用户可启用或新增主题目录（如 mxxx 商业主题）。每个主题目录包含模板文件（.dwt）、样式（css）、脚本（js）、图片（images）以及可选的扩展入口（inc/..from_theme.php）。后台通过控制器与服务提供主题列表、启用、删除、参数同步等功能；前台在请求时根据当前生效主题选择模板并加载扩展。
graph TB
A["前台请求"] --> B["路由与控制器<br/>PageController"]
B --> C["主题策略<br/>SiteThemePolicy"]
C --> D["主题目录<br/>theme/{slug}"]
D --> E["模板文件<br/>.dwt"]
D --> F["静态资源<br/>css/js/images"]
B --> G["主题扩展加载器<br/>ThemeExtensionLoader"]
G --> H["主题扩展脚本<br/>inc/..from_theme.php"]核心组件
- 站点主题策略：负责判定当前生效的主题目录名，并在未授权且为商业主题时使用默认主题回退。
- 后台主题控制器与服务：提供主题列表、启用、删除、参数同步、模块支持同步等能力。
- 前台页面控制器：按当前主题查找并渲染对应模板，若不存在则回退到通用模板。
- 主题扩展加载器：在路由解析后、控制器执行前，按需加载主题扩展脚本，注入模板变量。
架构总览
下图展示了从后台设置主题到前台渲染的完整链路，包括策略判断、模板选择与扩展加载。
sequenceDiagram
participant Admin as "后台"
participant ThemeCtrl as "ThemeController"
participant ThemeSvc as "ThemeService"
participant Policy as "SiteThemePolicy"
participant Front as "前台控制器"
participant Loader as "ThemeExtensionLoader"
Admin->>ThemeCtrl : 启用/删除/同步主题
ThemeCtrl->>ThemeSvc : enable/delete/sync
ThemeSvc-->>Admin : 结果(含缓存清理/数据同步)
Front->>Policy : effectiveTheme()
Policy-->>Front : 返回生效主题目录名
Front->>Front : 选择 theme/{slug}/xxx.dwt
Front->>Loader : loadForRoute(module, action)
Loader-->>Front : 注入模板变量(可选)
Front-->>Admin : 渲染页面详细组件分析
主题策略与生效主题
- 生效主题计算：读取配置中的 site_theme，若触发阻断条件（未授权 + 商业主题 + 正式域名），则强制回退到 default。
- 阻断条件：通过策略方法判断是否禁用当前商业主题，避免未授权环境使用受限主题。
flowchart TD
Start(["进入 effectiveTheme"]) --> ReadCfg["读取 site_theme"]
ReadCfg --> CheckBlock{"是否触发阻断?"}
CheckBlock -- "是" --> Fallback["回退到 default"]
CheckBlock -- "否" --> UseCfg["使用配置的 site_theme"]
Fallback --> End(["返回生效主题"])
UseCfg --> End后台主题管理
- 主题列表：扫描 theme 子目录，解析每个主题的元信息（名称、版本、作者、截图等），并标注是否为云主题。
- 启用主题：将 default 主题复制到目标主题目录（非 default），写入配置，并根据主题声明的缩略图尺寸更新相关配置，最后清理模板编译缓存。
- 删除主题：删除主题目录，清理云端更新时间戳，删除关联的图片附件，并清理主题相关数据行。
- 模块支持同步：从云端获取 need_module，或本地推导已安装模块集合，写入主题支持模块配置。
classDiagram
class ThemeController {
+index()
+install(request)
+enable(formRequest)
+destroy(formRequest, request)
+module()
+moduleClear()
+set(request)
}
class ThemeService {
+buildThemeListData(site_theme, theme_blocked)
+enableTheme(slug)
+deleteTheme(slug)
+syncSupportModuleFromApi()
+ensureThemeParameterRows()
-parseThemeMeta(slug)
}
ThemeController --> ThemeService : "调用"前台模板选择与扩展加载
- 模板选择：控制器根据当前主题目录拼接模板路径，若存在同名 .dwt 则渲染该模板，否则回退到 page.dwt。
- 扩展加载：在路由解析后、控制器执行前，检查主题 inc/..from_theme.php 是否存在并通过 SQL 安全校验，随后初始化 Portal 上下文并 include 该脚本以注入模板变量。
sequenceDiagram
participant Ctrl as "PageController"
participant Policy as "SiteThemePolicy"
participant Ext as "ThemeExtensionLoader"
Ctrl->>Policy : effectiveTheme()
Policy-->>Ctrl : 返回 slug
Ctrl->>Ctrl : 构建 theme/{slug}/xxx.dwt 路径
Ctrl->>Ext : loadForRoute(module, action)
Ext-->>Ctrl : 注入变量(可选)
Ctrl-->>Ctrl : 渲染模板主题元数据与云主题识别
- 元数据解析：从主题 style.css 头部注释解析主题名、URI、描述、版本、作者等信息，并生成截图 URL。
- 云主题识别：目录名匹配 m\d{3} 模式即视为云主题，用于后续预览与模块支持逻辑。
主题模块支持与过滤
- 模块支持同步：从云端接口获取 need_module，若为空且非商业主题，则合并已安装模块集合写入配置。
- API 过滤：云服务 API 配置排除某些基础模块 unique_id（如 fragment、box），以避免重复提示安装。
依赖关系分析
- 控制器依赖服务：ThemeController 依赖 ThemeService 完成主题管理的核心业务。
- 策略解耦：SiteThemePolicy 独立于控制器，提供生效主题判定，便于前后端一致使用。
- 扩展加载时机：ThemeExtensionLoader 在路由阶段之后、控制器之前执行，确保上下文就绪。
graph LR
TC["ThemeController"] --> TS["ThemeService"]
TC --> SP["SiteThemePolicy"]
PC["PageController"] --> SP
PC --> TEL["ThemeExtensionLoader"]性能与缓存
- 模板编译缓存：启用主题后会清理模板编译缓存目录，确保新主题立即生效。
- 扩展加载优化：仅在路由已知后加载主题扩展脚本，避免每次请求都执行全部赋值逻辑。
- 建议实践：
- 对主题内 CSS/JS 进行压缩与合并，减少请求数。
- 使用浏览器缓存与 CDN 加速静态资源。
- 增量更新主题资源时，变更文件名或添加版本号查询参数以绕过缓存。
安全与权限控制
- 主题阻断：在未授权且为商业主题的情况下，强制回退到默认主题，防止未授权使用受限主题。
- 扩展脚本安全：加载主题扩展脚本前进行 SQL 关键字白名单校验，降低恶意代码注入风险。
- 路径访问控制：模板选择基于主题目录名与固定文件名，避免任意路径遍历。
- 建议实践：
- 严格限制主题目录命名规范（如仅允许字母数字与短横线）。
- 对上传的资源进行类型与大小校验，禁止执行性文件。
- 使用服务器层的安全头与访问控制策略保护敏感目录。
打包与部署
- 主题包结构：每个主题目录应包含 css、js、images、inc 及模板文件（.dwt），并在 style.css 头部提供元数据注释。
- 版本控制：建议使用 Git 管理主题，利用分支与标签发布不同版本；部署时通过 CI/CD 推送至服务器。
- 增量更新：修改主题资源后，更新主题元数据版本并清理模板缓存；前端资源可通过文件名哈希或查询参数实现增量刷新。
- 云端集成：商业主题可通过云服务进行预览与模块支持同步，提升交付效率。
故障排查指南
- 主题未生效：
- 检查生效主题策略是否触发阻断（未授权 + 商业主题 + 正式域名）。
- 确认启用主题后是否清理了模板编译缓存。
- 模板找不到：
- 确认主题目录下是否存在对应的 .dwt 文件，否则将回退到 page.dwt。
- 扩展不加载：
- 检查 inc/..from_theme.php 是否存在并通过 SQL 安全校验。
- 模块支持异常：
- 重新执行模块支持同步，或清空本地缓存后重试。
结论
DouPHP 的多主题资源管理通过清晰的策略、控制器与服务分层，实现了主题隔离、覆盖与动态加载。结合模板编译缓存、扩展加载时机控制与云端模块支持同步，能够在保证安全性的前提下提供流畅的主题切换体验。建议在生产环境中遵循资源压缩、版本化与增量更新的最佳实践，以提升性能与可维护性。