简介面向Discuz!站长、PHP开发者与网络维护人员这份资源集成DZ论坛与克米模板3.5版本提供一整套可用于实际部署的模板文件和配套教程解决论坛搭建中界面单一、扩展功能不足等问题。压缩包共1755个文件大小约52.45MB其中PHP文件达818个构成模块功能核心HTM、CSS、JS文件负责页面结构与前端交互JPG、PNG、GIF等图片素材用于模板视觉呈现XML、TXT等文件则承担数据与说明配置整体结构清晰便于按需调用。克米模板3.5版本聚合了微信整合、首页风格定制、全文阅读、图片展示、短信验证、HTTPS安全支持、作者帖子模块、19楼社区式展示和颜色主题定制等实用组件既能美化社区界面又显著提升用户互动和访问安全。对希望深入理解Discuz!模板机制、进行二次开发或快速搭建生产环境的读者而言教程结合组件配置思路提供了可操作的参考路径。目前已有162人学习下载。1. DZ论坛碰上克米模板3.5第一批死在解压之后“DZ论坛克米模板3.5版本教程.rar”这种压缩包很多人以为是双击解压、按说明上传就能出效果真正动手才发现坑位比想象中多。DZ论坛升级到 Discuz! X3.5 之后PHP 版本、数据库编码、UCenter 通信方式和老版本完全不是一回事克米模板 3.5 版本作为适配新架构的产物目录结构、DIY 导入方式、后台设置路径都有自己的一套逻辑。这篇不会去复述某份打包说明而是按“模板机制 → 安装落地 → 故障排查 → 二次修改”的顺序把从拿到 rar 到门户首页正常渲染、DIY 不丢数据的完整路径讲透。新手能照着操作熟手重点看第 4 章的兼容边界和第 5 章的修改原则这些才是 3.5 版本真正值得花时间的部分。2. 拆开 rar 看克米模板目录结构、DIY 机制与 X3.5 的兼容边界2.1 一个标准克米 3.5 模板包里应该有什么解压后先别急着上传把目录结构看明白能省掉一半的排错时间。常见的克米 3.5 模板包内会包含这几类内容内容典型路径作用模板主目录template/kemi_35/存放模板的 htm 文件、CSS、JS、图片门户 DIY 文件template/kemi_35/diy/或包内独立diy/目录门户首页、频道页的模块布局 XML说明文档安装说明.txt或教程.pdf版本要求、上传路径、后台操作顺序配套插件source/plugin/部分版本带幻灯片、分类信息增强等依赖插件字体与图标库static/或模板内font/模板自带 iconfont用于导航和模块标题这里有个关键点克米模板从早期版本开始就是“模板 DIY 布局数据 配套插件”三层结构。模板文件只负责页面框架首页那些模块里的图片、标题、链接全部存在门户 DIY 的 XML 里。也就是说即使模板文件上传正确只要 DIY 数据没导入前台看到的只是一个空的模板壳子栏目位全白、底部推荐位全空。很多人在这一步误以为模板坏了其实只是缺了导入动作。2.2 为什么老版克米模板不能直接套到 X3.5 上Discuz! X3.5 相比 X3.4 有一个对模板生态影响深远的调整数据库默认采用 UTF8MB4且系统强制校验common_template表中的模板版本标识。老模板文件里的template/xxx/如果还沿用common/、forum/下旧的函数命名空间在 X3.5 下轻则功能按钮不显示重则直接白屏。从工程角度看X3.5 的模板机制有几处硬性变化PHP 版本基线X3.5 推荐 PHP 8.1老模板里chr()、ereg()这类写法在 PHP 8 下直接报错表现为页面顶部出现 Deprecated 警告或者整页 500。UCenter 通信X3.5 将 UCenter 独立成单独目录模板里如果直接调用ucenter相关函数或老接口可能出现登录状态不同步。变量作用域模板 htm 文件里使用$_G[setting]的覆盖面更广但部分变量在 X3.5 中改了结构例如$_G[setting][rewritestatus]与伪静态规则的耦合更深。HTML 版本X3.5 默认模板已经不用旧式table布局克米 3.5 版本改用div flex重写前端这意味着老的 JS 特效库需要同步升级直接覆盖会冲突。所以拿到“3.5 版本”的包第一件事是确认template/kemi_35/下的common/extend_common.css存在且非空这是克米 3.5 与 X3.4 模板在文件层最大的区别之一。没有这个文件说明版本发错或文件不完整别冒险往下传。2.3 模板渲染链路风格、模板与 DIY 数据是怎么拼在一起的Discuz! 的页面渲染顺序大致是用户请求 → 核心程序加载$_G[style]→ 通过template()函数定位到风格目录下的 htm 文件 → 解析模板变量 → 输出 HTML。克米模板的 DIY 数据走的是另一条线门户页面portal.php读取common_diy_data表中的序列化数据再把它嵌入模板的!--[diydiyXX]--占位符中。理解这条链路排错就会非常快页面框架错乱但模块数据还在 → 模板的 CSS 没加载或加载顺序不对页面框架正常但模块数据全空 → DIY 数据没导入或者导入到了错误的应用把门户 DIY 导入了论坛首页整页白屏 → 模板文件中存在 PHP 8 不兼容的写法或依赖插件未启用。这部分要记住一句经验克米模板的后台设置项和 DIY 模块之间是“松耦合”。后台“模板设置”里改的是配色、轮播时长、QQ 客服开关这类字段它们通过common_plugin或模板自带的配置表存储而首页每个模块展示什么内容靠的是 DIY 里的模块数据源两者互不干扰。这解释了为什么很多人改了后台颜色没反应——因为那个元素可能根本是 DIY 模块里的 HTML 背景色需要去 DIY 模块属性里改而不是后台。3. 从 rar 到可访问DZ论坛克米模板的最小安装步骤3.1 环境与权限这一步错了后面全白搭安装模板前先在 SSH 终端确认 DZ论坛运行环境满足克米 3.5 的基本要求。用如下命令检查php -v # 期望输出 PHP 8.1 或更高版本例如 PHP 8.1.25如果站点跑在 PHP 7.4 甚至更低克米模板装进去大概率出现页面打不开。这时优先通过面板把 PHP 切到 8.1 再继续。目录权限方面Discuz! 的模板文件和缓存目录需要 Web 用户可写可读检查方式ls -ld /www/wwwroot/你的站点/data/template # 期望输出 drwxrwxr-x 或 drwxr-xr-x属主为 www 或当前 Web 用户data/template是模板编译缓存目录DZ 每渲染一次 htm 文件都会在这里生成对应的xxx.tpl.php缓存文件。如果这个目录不可写前台页面会直接显示 500后台却看不出任何异常。另外data/diy目录也要可写DIY 数据导入和编辑都要写这个目录。3.2 上传模板并完成基础启用把 rar 中的template/kemi_35整体上传到 DZ 根目录下的template/文件夹中。注意检查是否多了一层嵌套比如上传后变成template/kemi_35/kemi_35/这种路径会导致后台无法识别模板。上传完成后到后台执行启用操作后台 → 界面 → 风格管理找到“克米模板 3.5”对应的风格条目点击“安装”安装完成后点击“启用”并设为默认风格。如果后台风格列表里没有出现新模板多半是模板文件里的common/目录缺失或者template/kemi_35/下没有style_*.css文件。可以把克米自带的style_1_kemi.css这类文件视为风格存在的标志。3.3 门户 DIY 导入与导航、Logo 的接驳模板启用后需要完成门户 DIY 的导入这是克米模板能否呈现演示站效果的核心环节。操作路径前台访问portal.php确保门户功能已开启点击页面右上角“DIY 导入”在弹出的窗口中选择“导入”选择模板包中的diy/portal_index.xml或类似名称的 XML 文件勾选“覆盖当前页面的 DIY 数据”确认导入。导入完成后需要设置 Logo 和导航。克米模板的 Logo 一般不是直接换文件而是在后台“界面 → 风格管理 → 克米模板 3.5 → 编辑”里填写 Logo 图片地址。如果填写后不生效检查是否把地址写成了绝对路径http://...部分版本只支持相对路径写成/static/image/kemi/logo.png更稳定。3.4 伪静态与缓存收尾前必须做的两件事克米模板的很多链接门户频道、文章页依赖伪静态规则不配置的话会有两个结果一是页面 URL 带?mod参数二是部分模板内部 JS 解析链接出错导致点击无反应。以 Nginx 为例在站点配置文件的server段中加入 Discuz! X3.5 的伪静态规则location / { if (!-e $request_filename) { rewrite ^([^\.]*)/topic-(.)\.html$ $1/portal.php?modtopictopic$2 last; rewrite ^([^\.]*)/article-([0-9])-([0-9])\.html$ $1/portal.php?modarticlearticleid$2page$3 last; rewrite ^([^\.]*)/forum-(\w)-([0-9])\.html$ $1/forum.php?modforumfid$2page$3 last; rewrite ^([^\.]*)/thread-([0-9])-([0-9])-([0-9])\.html$ $1/forum.php?modviewthreadtid$2extrapage\%3D$4page$3 last; } }配置完成后重载 Nginxnginx -t nginx -s reload最后一步后台 → 工具 → 更新缓存勾选“模板缓存”和“DIY 模块分类缓存”确定。这一步的作用是清掉可能残留的旧模板编译文件否则前台可能仍渲染上一套风格。4. 装上就动手排查克米模板在 DZ论坛上的 6 个高频故障现象直接原因最快处理风格列表找不到模板目录嵌套错误或缺少common/目录检查template/kemi_35/下是否有common/DIY 导入报“模块ID 冲突”当前页面已存在相同 diy 节点先清空页面再导入门户首页 404门户未开启或伪静态规则未生效后台全局开启门户首页错位、图标全 XCSS/JS 路径 404检查资源引用是相对还是绝对路径后台模板设置项不生效字段写入的是common_plugin与 DIY 缓存不同步更新缓存后重试升级 X3.5 小版本后模板异常模板中使用了废弃函数等待模板适配或回退版本4.1 后台风格列表里找不到克米模板除了目录嵌套还有一个隐蔽原因模板名与 Discuz! 保留字冲突。template目录下的文件夹名必须是英文、数字或下划线且不能以数字开头。如果克米模板包解压后目录名是中文或含空格后台会直接忽略它。处理办法是重命名为kemi_35之类的合法名称然后同步修改模板文件里所有写死路径的地方——通常只有common配置和css_common.htm中才有。4.2 DIY 导入报错或导入后空白导入报错集中在两类XML 文件编码问题和模块属性冲突。克米 3.5 的 DIY 文件应保存为 UTF-8 无 BOM 格式用文本编辑器打开看 XML 声明是否包含encodingUTF-8。如果之前被人用记事本另存过可能带 BOM 头Discuz! 解析时会在第一个节点前读到不可见字符表现为“DIY 导入失败”且无具体错误信息。导入后空白常见原因是模块数据源来自“自定义 HTML”而自定义 HTML 中写死了当前服务器不存在的资源绝对地址或调用了未启用的插件函数。这时先别急着重导退出 DIY 模式后刷新页面看空白面积——如果是单个模块空白编辑该模块删除重加如果是整页空白则回归检查第 2 章说的模板 DIY 松耦合问题。4.3 门户首页 404 或跳回 defaultDZ论坛门户功能默认不开启克米模板的演示站首页通常通过portal.php展示。后台“全局 → 门户设置”中开启门户功能后仍 404 的话大概率是 Nginx 伪静态规则没加载。注意 Discuz! X3.5 的伪静态对portal.php?modindex没有直接 rewrite必须保证访问域名/时默认文档解析到portal.php或直接跳转到门户首页。许多环境默认首页是forum.php这会导致 URL 变成域名/forum.php克米模板的主页模块全部丢失。最直接的验证方法临时关闭伪静态直接访问域名/portal.php如果能正常显示克米首页说明问题出在伪静态规则而非模板本身。4.4 首页错位、图标全 X先查资源路径错位问题的排查路径按“CSS 404 → JS 404 → 图片 404”的顺序走。打开浏览器开发者工具看 Network 面板里红色状态的文件路径。克米模板的静态资源通常分布在两个位置模板自己的static/目录和 DZ 核心的static/目录。如果请求的 CSS 路径是/template/kemi_35/style_1_kemi.css返回 404则上传时该文件确实缺失重新上传。如果文件存在但返回 200 后样式不生效则属于加载顺序被第三方插件破坏。克米模板在common/header.htm里按固定顺序加载 CSS某些插件会在global_usernav_extra钩子里插入自己的样式并覆盖.wrap等类名。这时去后台禁用最近安装的插件逐个排查比在 CSS 文件里找覆盖源高效得多。4.5 模板自带设置项不生效克米 3.5 的模板设置项一般存在common_setting表中这也是 DZ 标准做法。但模板设置页有缓存机制修改保存后立即刷新前台可能仍是旧值必须等后台“更新缓存”动作写入data/setting.php编译文件。如果更新后仍无效打开数据库检查SELECT * FROM pre_common_setting WHERE skey LIKE %kemi%;重点关注kemi_style_setting这类字段的值。若字段存在但前台不读取说明模板 htm 里读取的变量名与存储的键名不一致这是模板版本与文件版本错配导致的重新上传模板文件覆盖是最省事的解法。4.6 升级 Discuz 小版本后模板异常Discuz! X3.5 每次小版本更新都可能调整模板引擎的逻辑例如 3.5.4 之后对checktplrefresh的判定更严格模板文件修改时间戳不更新时不再自动重新编译。这会导致一个诡异现象模板文件已经换新前台显示还是旧的。处理方法是后台更新缓存并强制编译删除data/template下对应模板名的*.tpl.php文件或在后台“工具 → 更新缓存”时勾选“模板缓存”。若升级后直接白屏进数据库执行DELETE FROM pre_common_template WHERE name LIKE %kemi%;然后回到后台重新安装模板。此操作只删模板注册记录不删文件可放心执行但需要重新设置默认风格。5. 克米模板的二次修改与性能检查清单5.1 改模板不破坏升级的三个原则克米模板的二次开发最优先推荐的做法是拿到模板后在template/kemi_35/common/下新建extend_common.css把自定义样式全部写在这个文件里不动模板自带的common.css。DZ 的模板机制会在公共头部自动加载 extend 系列文件后续克米更新时只需覆盖原文件自定义部分不会丢失。涉及 htm 文件的改动记录修改文件清单更新版本后逐项比对。一般克米模板核心文件集中在forum/viewthread.htm、forum/forumdisplay.htm和portal/index.htm这三个文件是改动高频区建议每次修改前先复制一份备份到本地。对于模板自带的 JS 特效不要直接改源码。克米 3.5 一般会预留配置接口例如轮播图的数量、切换间隔优先在后台模板设置里调。只有设置项覆盖不到的场景才动 JS并且只在文件末尾追加新代码块避免和原逻辑混在一起。5.2 交付前按清单过一遍把模板当作一个正式项目收尾时下面这张检查清单可以作为验收基准后台开启“模板缓存”和“DIY 缓存”关闭开发模式后前台无任何报错输出用手机端访问门户、列表页、内容页确认克米模板的响应式断点在 375px 和 768px 两个宽度下无横向滚动检查所有图片资源走 HTTP 还是 HTTPS混合内容会导致浏览器拦截模板自带的小图标在后台执行一次“校验文件”确认没有覆盖 Discuz! 核心文件用curl -I 域名/portal.php确认返回 200且响应头中包含Content-Encoding: gzip说明压缩已生效。这套流程走完后克米模板的安装与适配才算闭环。DZ论坛的模板折腾空间很大但边界也清楚——只要遵守模板与 DIY 分离、样式与结构分离这两个原则后续维护成本能压到最低。本文还有配套的精品资源点击获取