织梦cms本地调试教程

一、本地调试的目的

本地调试织梦CMS主要用于模板开发、标签测试、采集规则验证、功能二次开发等场景。相比直接在线上修改，本地调试响应快、可反复试验、不影响用户体验，是织梦开发的标准流程。

二、调试前的准备

安装本地环境（推荐phpStudy + PHP 7.4 + MySQL 5.7）。
完整安装织梦V5.8，能正常登录后台。
关闭PHP错误屏蔽，开启显示错误。
准备一个支持UTF-8的代码编辑器（VSCode、PhpStorm）。

三、开启PHP错误显示

调试期必须能看到错误，否则白屏时无从下手。修改 php.ini：

display_errors=On
display_startup_errors=On
error_reporting=E_ALL
log_errors=On
error_log=/path/to/php_errors.log

或在站点根目录 .htaccess 中临时开启：

php_flag display_errors On
php_value error_reporting E_ALL

四、织梦调试模式

织梦本身没有独立的 debug 模式，但可通过以下方式输出调试信息。

1. 模板标签调试

在模板中直接使用 {dede:php}var_dump($refObj->Fields);{/dede:php} 输出当前页变量。注意生产环境必须删除。

2. SQL调试

{dede:php}
$dsql->SetQuery("SELECT * FROM dede_archives WHERE id=1");
$dsql->Execute();
while($row=$dsql->GetArray()){
    var_dump($row);
}
{/dede:php}

3. 查看SQL日志

修改 /include/dedesql.class.php，在查询方法中临时加入 file_put_contents('sql.log', $query."\n", FILE_APPEND); 记录所有SQL。

五、模板调试技巧

1. 关闭模板缓存

调试模板时必须关闭缓存，否则改了看不到效果。后台 - 系统 - 系统基本参数 - 性能选项 - "是否启用模板缓存"设为"否"。

或手动清空 /data/tplcache/ 目录。

2. 常用标签测试

{dede:arclist row='5' typeid='1' orderby='pubdate'}
  标题：[field:title/]
  链接：[field:arcurl/]
  缩略图：[field:litpic/]
{/dede:arclist}

3. 标签不生效排查

检查标签闭合：{dede:xxx}...{/dede:xxx}
检查字段名拼写：[field:title/] 而非 [field:titel/]
检查栏目ID是否正确
检查模板文件编码是否为UTF-8无BOM

六、生成静态页调试

后台 - 生成 - 一键更新网站，观察是否报错。
单个栏目更新，定位问题栏目。
查看 /data/log/ 下的错误日志。
查看PHP错误日志（phpStudy - 错误日志）。

七、采集规则调试

后台 - 采集 - 采集节点管理 - 测试采集。
查看匹配到的字段内容是否符合预期。
调整正则或区域选择器，反复测试。
测试通过后再正式采集。

八、调试织梦后台功能

修改 /dede/ 下的PHP文件后，直接刷新后台页面即可生效。若开启了opcache，需重启PHP或执行 opcache_reset()。

九、使用断点调试（Xdebug）

进阶调试可安装Xdebug，配合VSCode/PhpStorm实现断点。

; php.ini
[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

十、注意事项

调试完成后必须关闭错误显示、删除临时调试代码、清空日志文件；上线前不要使用 root 数据库账号；模板中的 {dede:php} 标签有安全风险，生产环境建议禁用。

建议为每个项目建立独立的调试日志目录，使用日期命名便于追溯；养成"改一处、测一处、记一处"的习惯，能大幅减少返工。

十一、行动指引

初次调试建议先用织梦自带默认模板跑通全流程，再开始自定义模板开发；遇到问题善用 var_dump 与日志文件定位，避免凭猜测修改代码；调试环境与生产环境严格隔离，杜绝调试信息泄漏到公网。