PbootCMS模板修改常见错误与调试技巧：空白页、标签不解析、样式失效
修改PbootCMS模板时经常遇到页面空白、标签不解析、样式不生效等问题。掌握调试技巧，快速定位解决。
页面空白（白屏）。原因一，模板标签语法错误，大括号不配对或标签名写错。PbootCMS遇到模板解析错误可能显示空白。解决：开启调试模式，config/config.php里'debug' => true，页面会显示错误信息。或看runtime/log下的日志。原因二，引入了不存在的模板文件，{include file='notexist.html'}，检查文件名和路径。原因三，PHP错误，模板里用了原生PHP代码语法错，检查{php}标签里的代码。
标签不解析，前台显示{title}原文。原因一，模板文件后缀不是.html，PbootCMS只解析.html模板。原因二，标签在被include的文件里，但include路径错，文件没被引入。原因三，标签名拼写错，如{pboot:lists}（多了s），正确是{pboot:list}。原因四，标签在纯文本区域被转义了，检查模板源码。原因五，缓存没清，旧模板还在缓存里，后台清缓存或删runtime/cache目录。
列表不输出内容。{pboot:list}循环为空，检查：1. 栏目下有没有文章，空栏目当然没内容。2. num属性是否为0。3. 栏目是否绑定了正确模板。4. 列表标签是否写在list.html里（写在index.html里需要指定栏目：{pboot:list num=10 sort=栏目ID}）。5. 调试模式看有没有SQL错误。
图片不显示。模板里图片路径用了相对路径，子页面访问时路径错乱。解决：用{TPL}/images/logo.png，{TPL}自动替换为模板目录URL。或用绝对路径/template/default/images/logo.png。检查图片文件是否存在，大小写是否正确。CSS里的背景图路径相对于CSS文件位置，不是HTML，注意路径计算。
样式改了不生效。1. 浏览器缓存：Ctrl+F5强制刷新。2. CSS选择器优先级不够：原样式用了更高优先级（如ID选择器），你的class选择器被覆盖。F12-Computed看属性有没有被划掉，被划掉就是优先级问题，加更具体的选择器或!important测试。3. 改了错的CSS文件：模板可能引入了多个CSS，确认改的是生效的那个。F12-Sources看CSS文件路径。4. CSS语法错误：后面的样式失效，用CSS验证工具检查。5. PbootCMS缓存：清缓存。
JS报错导致功能失效。F12-Console看JS错误。常见：$ is not defined（jQuery没引入或顺序错），模板里的JS依赖jQuery但jQuery在后面引入。解决：jQuery放在所有JS前面。自定义JS写在模板底部，确保DOM加载完。PbootCMS模板自带的JS不要随便删。
移动端样式错乱。1. 没加viewport meta标签，head.html里检查。2. 固定宽度元素（如width:1200px）超出屏幕，改成max-width:100%。3. 浮动布局没清，移动端错位，用flex或grid替代。4. 字体太大，用媒体查询调小。5. 测试用真机，不要只靠浏览器模拟。
修改后网站500错误。通常是改了PHP文件或配置文件语法错。如果只改了template下的HTML/CSS，一般不会500。500时看Nginx错误日志/www/wwwlogs/域名.error.log，最后几行有PHP错误信息。恢复最近修改的文件，逐步排查。
调试工具清单。1. 浏览器F12：Elements看HTML，Console看JS错误，Network看请求，Sources看CSS/JS。2. PbootCMS调试模式：config.php里debug=true。3. 错误日志：runtime/log、Nginx error log、PHP-FPM log。4. 模板注释：在模板里加，看前台源码有没有输出，确认模板文件是否被加载。5. 对比法：和默认模板对比，找出差异。
高效修改流程。1. 备份模板。2. 小改一点，保存，清缓存，刷新测试。3. 出问题立刻回退，定位是哪处修改导致的。4. 不要一次性大改后再测试，出问题不知道哪错的。5. 改完在多端验证。
更新时间：2026-08-26 17:30:47