DokuWiki 插件开发要点总结表格（含日志、调试、缓存）
| 主题 |
说明 |
建议与注意事项 |
| 语法类型 |
块级语法 vs 内联语法 |
块级：使用 addEntryPattern / addExitPattern；内联：用 addSpecialPattern |
| 块级语法 |
可跨行，常以两个连续换行符（空行）断开段落或块 |
注意保留换行，避免影响下一个语法块匹配 |
| 内联语法 |
单行匹配，不跨行、不包含换行符 |
正则不要匹配 \n；适用于加粗、斜体、代码片段等 |
| getSort() |
控制语法插件的执行优先级，数字越小越早执行 |
避免语法冲突，基础语法如加粗斜体应优先 |
| handle() |
匹配时解析原始语法，返回结构化数据供 render() 使用 |
不输出内容，只解析和整理匹配数据 |
| render() |
根据 handle() 返回值渲染 HTML 或其他输出 |
根据 $mode 区分 xhtml、odt 等渲染方式 |
| 换行符处理 |
块级语法匹配中可包含换行，内联语法应避免换行 |
不当处理可能吞掉换行，导致后续语法失效 |
| 语法冲突常见问题 |
上一个语法块过度吞噬换行符，下一个语法块失去匹配前导 |
控制退出正则、避免贪婪匹配、合理设置 getSort() |
| 常见错误陷阱 |
退出语法模式使用贪婪正则或直接匹配多换行符 |
使用非贪婪正则，或分层处理换行逻辑 |
| 日志记录方式 |
Logger::log()、Logger::debug()、Logger::error() 分别记录信息、调试、错误日志 |
组件名建议使用 plugin.插件名，日志等级如 LOG_INFO、LOG_WARNING、LOG_ERR 等 |
| 调试方式：msg() |
使用 msg($msg) 向页面输出调试信息，支持类型标记（例如 INFO, DEBUG, ERROR） |
仅开发时使用，调试完务必移除 |
| 调试方式：dbg() |
快速输出变量或文本，仅在 $conf['debug'] = 1 时生效 |
开发调试极为方便，格式化输出，页面底部可见 |
| 调试方式：dbg_backtrace() |
输出调用栈信息，调试调用顺序与问题定位 |
配合复杂插件或钩子排查执行路径 |
| 缓存刷新方式：purge=1 |
强制刷新页面缓存，重走语法解析和渲染逻辑 |
用于开发调试时测试最新渲染效果 |
| 其他日志输出方式 |
var_dump()、print_r() 直接输出内容至页面（仅开发中使用） |
开发环境可用，正式环境应避免 |
| 开启调试模式 |
conf/local.php 中设置 $conf['debug'] = 1; |
配合 dbg()、Logger::debug() 使用 |
| 查看日志输出 |
DokuWiki 日志记录到 data/cache/log/ 目录（或服务器日志） |
持续追踪错误、调试信息 |
示例：在插件中使用 Logger 和 dbg
public function handle($match, $state, $pos, Doku_Handler $handler) {
Logger::debug('plugin.myplugin', 'Handling match at position: ' . $pos);
dbg(['match' => $match, 'state' => $state]); // 开发调试
return [$state, $match];
}
插件架构与生命周期
| 主题 |
说明 |
建议与注意事项 |
| 插件类型 |
DokuWiki 支持多种插件类型：语法、动作、管理、帮助、渲染等 |
根据功能需求选择合适的插件类型，可以实现多种类型的组合插件 |
| 插件注册 |
通过 plugin.info.txt 文件注册插件基本信息 |
必须包含 base、author、email、date、name、desc、url 等字段 PluginTrait.php:33-40 |
| 插件初始化 |
通过 register() 方法注册事件处理器 |
动作插件必须实现此方法，语法插件通过 getSort() 和连接方法注册 |
| 缓存控制 |
插件可通过 $renderer->nocache() 禁用页面缓存 |
动态内容插件应禁用缓存，但注意性能影响 renderer.php:94-99 |
错误处理与调试增强
| 主题 |
说明 |
建议与注意事项 |
| 异常处理 |
使用 try/catch 捕获异常，避免插件错误影响整个系统 |
插件加载失败会被 PluginController 捕获并显示错误信息 PluginController.php:130-133 |
| 错误处理器 |
DokuWiki 有内置的错误处理系统 |
严重错误会被 ErrorHandler 捕获并记录到日志 ErrorHandler.php:58-66 |
| 调试模式检测 |
使用 DebugHelper::isEnabled() 检查调试是否启用 |
避免在生产环境输出调试信息 |
性能优化
| 主题 |
说明 |
建议与注意事项 |
| 缓存策略 |
合理使用 DokuWiki 的缓存系统 |
静态内容使用缓存，动态内容考虑局部缓存或禁用缓存 |
| 资源加载 |
按需加载 JavaScript 和 CSS |
使用 script() 和 tpl_addStyle() 函数，避免不必要的资源加载 |
| 数据结构优化 |
处理大量数据时注意内存使用 |
使用迭代器或生成器处理大型数据集，避免一次性加载全部数据 |
国际化与本地化
| 主题 |
说明 |
建议与注意事项 |
| 语言文件 |
使用 lang/xx/lang.php 存储翻译字符串 |
通过 $this->getLang('key') 获取当前语言的翻译 |
| 日期与时间格式 |
考虑不同地区的日期时间格式 |
使用 DokuWiki 的 dformat() 函数格式化日期时间 |
安全性考虑
| 主题 |
说明 |
建议与注意事项 |
| 输入验证 |
始终验证和清理用户输入 |
使用 hsc() 函数转义 HTML，防止 XSS 攻击 |
| 权限检查 |
使用 auth_quickaclcheck() 检查用户权限 |
在执行敏感操作前验证用户权限 |
| CSRF 保护 |
使用 DokuWiki 的表单安全令牌 |
通过 formSecurityToken() 生成和验证安全令牌 |
示例：完整的插件调试与日志记录
public function handle($match, $state, $pos, Doku_Handler $handler) {
global $conf;
// 1. 使用 Logger 记录调试信息（始终写入日志文件）
Logger::debug('plugin.myplugin', "处理匹配：$match，状态：$state，位置：$pos");
// 2. 仅在调试模式下输出到页面
if ($conf['allowdebug']) {
dbg(['match' => $match, 'state' => $state, 'pos' => $pos]);
msg('插件处理中...', 0); // 0=信息, -1=错误, 1=成功, 2=通知
}
// 3. 记录错误（如有）
try {
// 处理逻辑
$result = $this->processMatch($match);
} catch (\Exception $e) {
Logger::error('plugin.myplugin', $e->getMessage(), $e->getFile(), $e->getLine());
return false;
}
// 4. 禁用缓存（如果内容是动态的）
if ($this->isDynamic) {
$handler->_addCall('nocache', [], $pos);
}
return $result;
}