作为一款常年低调的开源 Wiki 系统DokuWiki 给人的印象通常是“不需要数据库、PHP 就能跑、语法自成一体”。如果你已经习惯了 GitHub、Notion、Obsidian 这类工具里的 Markdown 写作体验初上手 DokuWiki 时大概率会被它那套独特的语法搞得有些别扭标题要用加粗要写**text**列表缩进还经常因为空格数不对而出错。这种情况终于要发生变化了。DokuWiki 新版本 Mort 发布后最重要的一件事就是原生支持 Markdown。确切地说是把 Markdown 作为一种可选的编辑语法不再强制用户只能使用传统的 DokuWiki 语法。与此同时这个版本对运行环境的要求也提高了部署 PHP 版本最低需要 8.2。这篇博客会围绕 Mort 版本做一次完整梳理先说清楚这次更新的核心意义再讲部署和升级时需要关注的环境变化最后通过完整示例演示如何启用 Markdown 编写页面并给出常见的升级踩坑和工程建议。1. DokuWiki Mort 版本到底改了什么很多人听到“原生支持 Markdown”的第一反应是“Wiki 系统支持 Markdown 不是早就有插件了吗” 确实DokuWiki 生态里一直有dokuwiki-plugin-markdown这类第三方方案用来提供 Markdown 解析支持。但插件方案和原生支持在实际使用体验上有很大区别。插件方案最大的问题在于兼容性和维护成本。第三方插件往往滞后于 DokuWiki 主版本更新而且解析行为难以和系统自身的语法高亮、页面重命名、标题锚点、目录生成等功能深度整合。你可能会遇到 Markdown 标题能渲染、但 TOC 无法正确识别标题级别的情况也可能在编辑页里正常一保存后某些特殊符号被转义得面目全非。Mort 版本的原生 Markdown 支持是把 Markdown 作为第一公民语法加入到核心渲染流程里。这意味着不需要额外装解析插件。Markdown 标题、列表、链接、表格等基础语法能被核心渲染器正确识别。系统内置的编辑工具栏能根据当前语法模式提供对应的插入按钮。渲染逻辑和页面缓存、权限控制、命名空间等核心能力在架构上保持一致。这种变化的价值不能只看“省一个插件”而是 DokuWiki 真正开始向现代 Markdown 工作流靠拢。它承认了一个现实大量用户的知识库和写作习惯已经建立在 Markdown 之上Wiki 系统如果继续守着老语法只会让新用户的学习成本越来越高。对个人站长或中小企业团队来说这个版本意味着如果你们之前因为 DokuWiki 语法上手成本而放弃它现在可以重新评估。轻量部署、无需数据库、文件即存储这些老优点还在门槛却降了一截。2. DokuWiki 的核心概念与语法模式选择在进入安装部署细节之前有必要先理清 DokuWiki 的几个基础概念。因为即使引入了 MarkdownDokuWiki 也不是一个“像 GitBook 那样按 Markdown 文件管理内容”的系统它有自己的页面和命名空间组织方式。2.1 页面Page和命名空间NamespaceDokuWiki 的页面存储在pages/目录下一个页面对应一个文本文件。不同于很多 Wiki 系统用数据库存内容DokuWiki 使用纯文本文件存储页面源码同时通过data/目录存放元数据和缓存。命名空间可以简单理解为“目录”。你在pages/下创建一个tech子目录就相当于有了一个tech命名空间。页面地址tech:php82会对应到文件pages/tech/php82.txt。在经典 DokuWiki 语法下页面文件的第一行几乎总是状态标记比如 Title 。但在 Mort 版本里如果你把一个页面标记为 Markdown 格式这个页面源码就可以直接使用.md风格语法系统会按 Markdown 来渲染。这里要特别注意页面文件的物理后缀并不一定代表语法模式。DokuWiki 并不是按.txt还是.md来判断渲染方式而是根据页面或命名空间的配置来决定使用 Markdown 语法还是 DW 语法。2.2 DW 语法和 Markdown 的区别功能DokuWiki 原生语法Markdown 语法一级标题 标题 # 标题二级标题 标题 ## 标题加粗**加粗****加粗**斜体//斜体//*斜体*或_斜体_无序列表* 项目两个空格- 项目链接[[https://example.com链接文字]]表格竖线和空格组合竖线加分隔行从对比可以看到两者有相似之处但差异也很明显。Markdown 的写法更接近程序员写文档的习惯尤其是标题只需要#链接用标准 Markdown 链接格式复制到 GitHub、Hexo、语雀等平台时可以无缝迁移。2.3 为什么 Mort 版本仍然保留双轨制对新用户来说可能有疑问既然支持了 Markdown为什么还要保留 DW 语法直接全面切换不是更好实际上DokuWiki 有大量存量站点这些站点的历史内容全部是 DW 语法。如果新版本直接把 Markdown 设为唯一语法老站点的内容会全部渲染异常等于强迫用户做全站内容迁移。双轨制是兼容存量与吸引增量最稳妥的方案。因此Mort 版本的选择是“按需开启默认兼容”。管理员可以配置默认语法也可以允许用户在页面级别自行选择。这是一种工程上务实的设计避免了一次性升级带来的内容不可控风险。3. 部署环境要求与迁移准备重点来了。新版本对运行环境的要求发生了变化尤其注意 PHP 版本。3.1 PHP 8.2 是硬性要求从 Mort 版本开始DokuWiki 的最低 PHP 版本要求是 8.2。如果搜索引擎或官方信息显示需要 8.2那就说明运行环境低于 8.2 时系统无法保证安装、安全更新和功能完整性。这意味着如果你现在运行的是 PHP 7.4 或者 8.0 的服务器不能直接下载新版本覆盖部署。必须先升级 PHP 运行环境再进行 DokuWiki 升级。查看当前 PHP 版本php -v如果版本过低在 Ubuntu/Debian 系统上可以通过第三方仓库安装 PHP 8.2 或更高版本sudo add-apt-repository ppa:ondrej/php -y sudo apt update sudo apt install php8.2 php8.2-cli php8.2-gd php8.2-xml php8.2-mbstring php8.2-curl php8.2-zip需要留意的是DokuWiki 不需要 MySQL 或 PostgreSQL所以不必额外装php-mysql扩展。不过建议把php8.2-xml、php8.2-mbstring等常见扩展装齐避免后续遇到依赖缺失问题。3.2 Web 服务器要求DokuWiki 官方支持 Apache、Nginx、IIS 和 Caddy 等主流 Web 服务器。由于不依赖数据库在 Nginx 下的配置比很多 PHP 应用都要简单。一个最基本的 Nginx 配置参考如下以 Ubuntu 22.04 为例server { listen 80; server_name wiki.example.com; root /var/www/dokuwiki; index index.php index.html; client_max_body_size 5M; location / { try_files $uri $uri/ dokuwiki; } location dokuwiki { rewrite ^/doku.php /doku.php last; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.2-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } location ~ /(data|conf|bin|inc)/ { deny all; } }这里一定要把data、conf、bin目录的访问禁止掉。DokuWiki 的所有用户页面、权限配置、缓存数据都存放在这些目录下如果 Web 服务器把它们当作静态资源暴露会带来严重的信息泄露风险。3.3 升级前备份清单无论你是从旧版本升级还是从零部署备份永远是第一优先级。DokuWiki 的备份比数据库应用更简单因为大部分内容就是文件但需要注意备份完整性。需要备份的目录至少包括/conf/ # 全部的配置文件 /data/ # 页面文件、媒体文件、Attic 历史版本、缓存 /lib/ # 已安装的插件和模板如果你做过自定义如果你不确定哪些目录发生了变化也可以直接全量备份整个 DokuWiki 根目录tar -czvf dokuwiki_backup_$(date %Y%m%d).tar.gz /var/www/dokuwiki在升级大版本之前强烈建议先在本地或测试环境做一次“备份 → 部署新版 → 验证页面 → 测试 Markdown 功能”的演练。未经测试直接在生产环境上传新版本一旦语法渲染出现问题可能影响所有用户的历史页面。4. DokuWiki Mort 安装与升级完整流程这里以 Linux 服务器为例演示从零安装 DokuWiki Mort 版本到启用 Markdown 的完整过程。如果你的服务器上已经存在旧版本可以直接看 4.3 节的升级部分。4.1 从零部署官方发布包一般是一个压缩文件。以 Mort 版本为例你需要先到 DokuWiki 官网或 GitHub Releases 页面下载最新发布包。cd /var/www wget https://download.dokuwiki.org/out/dokuwiki-xxxx.tgz tar -xzf dokuwiki-xxxx.tgz mv dokuwiki-xxxx dokuwiki这里xxxx表示实际发布版本号具体以官网下载页为准。解压之后需要确保 Web 服务器用户对data、conf、lib/plugins、lib/templates等目录有写入权限。sudo chown -R www-data:www-data /var/www/dokuwiki sudo chmod -R 755 /var/www/dokuwiki如果你是在本地开发环境测试为了保证目录可写也可以放宽权限但生产环境建议按最小权限原则配置。4.2 执行安装脚本浏览器访问http://your-server-ip/install.php会看到 DokuWiki 的 Web 安装界面。在安装页面里需要设置Wiki 名称你的站点名称。超级管理员用户名和密码。启用 ACL 权限控制建议启用。默认语言。安装完成后你会收到安全提示要求删除install.php文件。这一步不要跳过否则任何人都能重新运行安装脚本并覆盖管理员账号。sudo rm /var/www/dokuwiki/install.php4.3 旧版本升级注意事项如果是从旧版本升级不要直接覆盖到原有站点上。推荐的升级方式是“新目录部署 配置迁移”。# 1. 在站点根目录外下载新版本到临时目录 cd /tmp wget https://download.dokuwiki.org/out/dokuwiki-xxxx.tgz tar -xzf dokuwiki-xxxx.tgz # 2. 暂存新版本 sudo mv /tmp/dokuwiki-xxxx /var/www/dokuwiki_new # 3. 迁移配置和页面数据 sudo cp -a /var/www/dokuwiki/conf/* /var/www/dokuwiki_new/conf/ sudo cp -a /var/www/dokuwiki/data/* /var/www/dokuwiki_new/data/ sudo cp -a /var/www/dokuwiki/lib/plugins/* /var/www/dokuwiki_new/lib/plugins/ sudo cp -a /var/www/dokuwiki/lib/templates/* /var/www/dokuwiki_new/lib/templates/ # 4. 切换站点目录 sudo mv /var/www/dokuwiki /var/www/dokuwiki_old sudo mv /var/www/dokuwiki_new /var/www/dokuwiki这种方式最大的好处是留了一个完整的旧版本目录作为回滚点。如果新版本出现异常只需要把目录名调整回来即可不用重新上传旧代码。4.4 升级后立即要做的事升级后第一时间登录管理后台检查插件兼容性。部分老插件可能在 Mort 版本里无法正常工作需要逐个确认轻量级插件如果只是简单封装 DW 语法通常问题不大。深度依赖旧版渲染管道的插件可能需要等待作者适配。如果你在旧版本里安装了 Markdown 插件升级前务必先卸载或禁用避免和原生 Markdown 支持产生冲突。在管理后台的“扩展管理器”里可以看到哪些插件标记为不兼容或需要更新。5. DokuWiki 启用原生 Markdown 的配置方法安装完成后默认仍然使用 DW 语法。要在 Mort 版本里启用 Markdown需要修改配置。5.1 修改配置文件DokuWiki 的本地配置存放于/conf/local.php。你可以通过管理后台的“配置管理器”界面修改也可以直接编辑文件。如果你希望全站默认使用 Markdown 语法在conf/local.php中加入?php // 文件路径conf/local.php $conf[default_parse_mode] markdown;这个配置项的含义是把全局默认解析模式切换为 Markdown。需要注意的是DokuWiki 的解析并不是读取文件的扩展名而是以配置为准。如果只希望特定的命名空间使用 Markdown而其他页面保持 DW 语法可以在对应命名空间的conf/markdown.local.php中加入类似配置。不过更加简单易用的方式还是在页面级别通过编辑工具栏或页面配置来切换。实际使用中更推荐的做法是不要盲目改全局配置。如果你有一个存量站点历史页面全部使用 DW 语法直接把默认解析模式改成 Markdown会让所有旧页面排版错乱。稳妥的方案是新站点全站 Markdown存量站点新页面单独切换到 Markdown。5.2 通过管理后台配置如果你不想手工改配置登录管理员账号后进入管理后台 → 配置管理器在搜索框中输入parse找到“默认解析格式”或类似选项改成 Markdown 后保存即可。后台配置和直接改local.php是等效的系统都会把配置写入conf/local.php文件。5.3 编辑页面时切换语法模式如果只是新建个别 Markdown 页面在页面编辑页面的工具栏区域应该能看到语法模式切换按钮。不同来源的 UI 文案可能略有差异核心操作是新建页面。在编辑器中选择 Markdown 模式。正常使用 Markdown 语法编辑。保存后页面按 Markdown 渲染。如果页面模式选择对某些用户不可见需要检查用户组的权限设置。DokuWiki 的 ACL 控制很细管理员可以在权限规则中控制哪些用户能选择页面语法使用时要特别注意对匿名用户的限制。6. 在 DokuWiki 中使用 Markdown 的完整示例理论讲完下面通过一个实际场景从创建页面到渲染完成做全流程演示。6.1 场景设定假设我们要在 DokuWiki 中创建一个技术文档页内容是一段 PHP 8.2 环境配置说明要求使用 Markdown 语法编写并生成清晰的标题、代码块、表格和警告信息。6.2 创建 Markdown 格式页面在 DokuWiki 中创建页面有两种方式方式一在页面 URL 中直接输入新页面名。比如https://your-wiki/doku.php?idtech:php82-upgrade页面不存在时DokuWiki 会显示“该页面尚未创建”的提示点击“创建此页面”按钮即可编辑。方式二在已有页面上写入内部链接。例如编辑首页加入[[tech:php82-upgrade|PHP 8.2 升级指南]]保存首页后进入链接会跳转到新页面创建入口。在编辑器里将语法模式切换到 Markdown然后输入# PHP 8.2 升级指南 本文档记录 DokuWiki 服务从 PHP 7.4 升级到 PHP 8.2 的步骤。 ## 环境检查 升级前先检查 PHP 版本和已安装扩展。 bash php -v php -m升级步骤备份 DokuWiki 全部文件。添加 PHP 8.2 软件源。安装 PHP 8.2 和相关扩展。修改 Nginx 或 Apache 的 fastcgi 配置。重启 PHP-FPM 服务。常见问题问题原因解决方式页面打不开PHP-FPM 未重启重启php8.2-fpmMarkdown 没生效页面仍是 DW 模式切换语法模式保存后DokuWiki 会渲染出一个结构完整的 Markdown 文档。下面的代码块内容会保持原样展示标题层级和表格都按标准 Markdown 处理。 ### 6.3 验证 TOC 目录功能 DokuWiki 的一个优势是它能自动根据页面标题生成目录。使用 Markdown 后# 一级标题和 ## 二级标题会被识别为目录层级。如果你保存页面后在右上角或页首看不到目录说明该页面可能关闭了目录功能或当前模板对 Markdown 标题的 TOC 支持还不完整。 在 DokuWiki 中可以通过配置控制目录显示深度默认情况下不需要专门设置。如果出现“标题能渲染但目录不显示”的情况优先检查该模板的版本是否支持 Mort然后再看页面开头是否包含 ~~NOTOC~~ 这类禁用目录标记。 ### 6.4 嵌入代码块 Markdown 模式的代码块外层语法与 DW 语法有差异 DW 语法代码块 text code php echo hello; /codeMarkdown 语法代码块需在 Markdown 模式下php echo hello; 如果你已经在 Markdown 模式使用code标签系统不一定会正确解析。这里需要格外注意不要混用两种嵌套规则解析器遇到不认识的语法时会按纯文本输出导致页面展示大段原始代码。6.5 图片与媒体文件DokuWiki 有自己的媒体管理机制图片需要通过doku.php?id页面名media文件名这类地址访问。在 Markdown 语法里插入图片仍然建议先通过编辑器工具栏上传到 DokuWiki 的媒体库然后引用媒体地址。直接写相对路径可能会因为命名空间解析差异导致图片无法显示。一个在 DW 页面内很容易被忽略的坑在 Markdown 模式下同样存在。7. DokuWiki Markdown 模式的配置项与扩展建议正式集成到团队工作流之前建议理解几个和 Markdown 模式相关的配置点。7.1 语法模式与渲染缓存DokuWiki 使用缓存来提高页面渲染速度。当你从 DW 语法切换到 Markdown 模式后对于已经存在的页面旧的渲染缓存不会自动失效。如果出现页面内容更新了但展示还是旧版或者语法切换后页面没有立即变化试着在管理员后台清除缓存。# 手动清理缓存目录 sudo rm -rf /var/www/dokuwiki/data/cache/*注意这一步会清掉所有页面缓存第一次访问页面时会重新生成相当于用 CPU 换一次缓存重建。如果站点页面量很大在访问高峰时段做这个操作会明显增加服务器压力建议在低峰期进行。7.2 Markdown 扩展与标准 MarkdownDokuWiki 原生 Markdown 支持的核心是 CommonMark 语法。换句话说DokuWiki 的 Markdown 解析以标准 Markdown 为主并在此基础之上扩展了少量 Wiki 风格的功能。如果你之前用过 GitHub Flavored Markdown也就是 GFM注意以下几点差异任务列表- [ ]是否原生支持取决于 Mort 版本是否启用了对应扩展。如果没有启用会被渲染成普通列表。删除线~~text~~在某些 Markdown 方言中是标准语法在 DokuWiki 里需要验证是否支持。比较保险的替代做法是使用deltext/del。表格语法管道符一般支持但在单元格内使用竖线转义字符时要特别小心DokuWiki 解析在某些历史版本中会出错。如果你在写作中依赖 GFM 的扩展语法建议先在测试环境建一个页面把计划用的语法逐项做一次渲染验证再决定是否全量投入使用。7.3 插件使用的过渡策略对于原本使用 Markdown 插件的站点升级到 Mort 后第一步是禁用第三方 Markdown 插件。然后在测试页面尝试原始 Markdown 内容。如果渲染差异过大需要逐步调整格式而不能一次性全站切换。这个过程中比较推荐的迁移路径是保留旧版本站点不动。在新版本后台新增少量 Markdown 测试页。对比渲染效果。确认稳定后再考虑将主要知识库从 DW 语法迁移为 Markdown。对于历史 DW 页面如无必要不强行转换。8. 升级到 Mort 版本的常见问题与排查思路在实际部署过程中最常见的几类问题可以整理成排查表方便收藏问题现象可能原因排查方式解决方案安装页面打不开PHP 版本过低或缺少扩展查看php -v和 PHP-FPM 错误日志升级到 PHP 8.2 并安装必需扩展升级后页面排版全乱默认解析模式改成了 Markdown但旧内容是 DW 语法检查conf/local.php中的default_parse_mode恢复 DW 默认模式或分批迁移内容Markdown 标题能渲染但没有目录当前模板不完全兼容 Mort查看模板更新版本切换默认模板测试或更新模板版本保存 Markdown 页面后显示原始源码编辑器没有成功切换语法模式重新编辑页面检查模式状态在页面级重新选择 Markdown 模式升级后某些文章代码块引号消失第三方 Markdown 插件与原生解析冲突禁用插件后重新渲染统一使用原生 Markdown 模式页面访问 403data目录权限不正确或 Nginx 匹配到错误 location检查 Nginx 配置和目录权限修改 location 规则禁止直接访问data下的.txt文件install.php一直有安全提示删除后仍然访问旧缓存清除浏览器缓存或检查反向代理缓存确认install.php已被移除如果你遇到的报错不在上表第一排查入口是 /data 目录下的日志文件。DokuWiki 在很多情况下会把异常信息写到/data/目录内的日志文件而不是直接输出到浏览器。注意查看data/目录下的dokuwiki.log或类似的日志文件。9. Mort 版本部署与团队协作的最佳实践DokuWiki 之所以能在众多现代 Wiki 工具中持续存在核心优势是没有数据库依赖、文件可移植性强。Mort 引入原生 Markdown 后这个优势变得更加明显。9.1 内容文件可以直接做版本管理DokuWiki 的页面存储为纯文本文件天然适合纳入 Git。团队中如果有多人维护同一套知识库可以定期把pages/目录推送到内部 Git 仓库实现内容版本回滚和变更审计。cd /var/www/dokuwiki git init git add pages/ data/pages/ git commit -m init dokuwiki pages即使 DokuWiki 系统本身崩溃只要pages/目录完好所有内容都还在。这类“按文件存储”的特性在迁移场景下尤其有价值你甚至可以把 Markdown 页面导出后平行迁移到 Hugo、MkDocs 等静态站点生成器。9.2 建议新项目直接用 Markdown如果你是在 Mort 版本上新建团队知识库强烈建议从第一天起就默认使用 Markdown。理由有三点团队成员大概率早已熟悉 Markdown不用再学 DW 语法的各种空格缩进规则。Markdown 内容可以低成本迁移到其他平台。AI 编程助手和静态文档工具对 Markdown 的解析支持优于 DW 语法。9.3 严格控制 ACL 和匿名访问DokuWiki 作为 Wiki 系统如果允许匿名用户编辑很容易被滥用。生产环境部署时建议做好两步第一步在 ACL 中关闭匿名用户的编辑和上传权限只允许登录用户操作。* ALL 0 * user 8第二步检查conf/local.php中是否启用了适当的权限机制。ACL 文件在conf/acl.auth.php修改时最好先备份因为它控制着所有访问规则。9.4 配置 HTTPS所有 Wiki 内容都应该通过 HTTPS 提供访问尤其是团队内部知识库。如果只是公司内网访问也建议在 Nginx 反向代理层终止 TLS。现代搜索引擎对 HTTPS 页面的收录优先级也更高。9.5 关注版本更新节奏Mort 是一个功能性大版本后续补丁版本会持续修复安全问题。DokuWiki 的安全更新相当活跃建议订阅官方更新通知保持版本始终在最新补丁级别避免因为长期不升级而暴露在已知漏洞中。10. 总结与下一步实践方向Mort 版本的原生 Markdown 支持没有让 DokuWiki 变成另一个静态博客系统也没有让它失去轻量优势。它做的是把 DokuWiki 的传统强项例如无需数据库、文件存储、权限管理完善和现代 Markdown 工作流做了一个务实的融合。如果你将 DokuWiki 部署在 PHP 8.2 环境里并把新站点默认语法设置为 Markdown那么你的团队既能继续享受 DokuWiki 带来的“零数据库、页面即文件”的易维护性又能用大家已经熟悉的语法快速产出文档。这个改变对于那些原本不愿学习 DokuWiki 独有语法的开发者绝对是迁移到 DokuWiki 的好时机。对于存量 DW 页面不必急着全站转换。先在测试环境升级建立几个 Markdown 页面做对比把渲染差异、模板兼容性和用户权限问题全部摸清再逐步扩大 Markdown 的使用范围。下一步建议你做的事情很简单准备一台 PHP 8.2 的测试服务器。下载 Mort 发布包。在一个临时域名上部署并启用 Markdown。把团队里最常用的三份文档迁移为 Markdown 格式验证渲染效果。确认没有明显问题后再制定正式站点的升级计划。DokuWiki 的吸引力不在于它有多炫酷而在于它把“写文档”这件事的成本降到足够低。Mort 版本补上了 Markdown 这一课之后它更像是那个“低调但能打”的本地 Wiki 工具值得你重新打开官网看一眼。