企业官网建设流程全解析

如果你所在团队的文档一直放在 DokuWiki 里，那么看到“DokuWiki 原生支持 Markdown”这条消息时，第一反应大概率不是兴奋，而是困惑：维基系统不是都有自己的语法吗？为什么要去适配 Markdown？

这个问题恰恰问到了点子上。过去几年，Markdown 已经从“程序员写 README 的小工具”变成了跨岗位协作的事实标准。产品经理写需求、运营写活动文案、技术作者写文档、AI 工具接收上下文，几乎都默认“Markdown 格式”。相比之下，DokuWiki 那套自成一派的标记语法虽然简洁，却成了第三方工具链和新人上手之间的隐形门槛。

这次发布的 DokuWiki 新版本代号为 Mort，最大的变化就是把 Markdown 支持放进了核心能力里，而不是继续依赖第三方插件。与此同时，部署环境的要求也提升到了 PHP 8.2。对老用户来说，这既是一个内容格式层面的好消息，也是一次需要认真规划升级的运维事件。

这篇文章会从 DokuWiki 的底层层逻辑讲起，分析它为什么选择在核心层支持 Markdown，并给出一套从 PHP 8.2 环境准备、安装部署、内容迁移、语法兼容到安全排查的完整实践路径。无论你是在公司内部搭建知识库，还是维护一个长期运行的公开 Wiki，都建议把这篇收藏起来，等真正升级的时候对照操作。

1. 为什么要关注“维基原生支持 Markdown”这件事

在很多团队里，“要不要用 DokuWiki”和“要不要用 Markdown”根本不是同一个问题。DokuWiki 的优势在于：不需要数据库、页面以纯文本文件存储、权限模型干净、部署简单，非常适合内部知识库和中小型项目文档。而 Markdown 的优势在于：语法通用、适合版本管理、能被各种编辑器和 AI 工具直接解析。

过去，这两者之间靠插件缝合。想用 Markdown 语法写 DokuWiki 页面，需要额外安装并维护一个语法插件，而插件与核心版本的兼容性往往滞后。一旦 DokuWiki 升级，插件挂掉，面对一堆用 Markdown 写好的页面，处理起来会非常痛苦。

原生支持则完全不同。它意味着 Markdown 语法解析与渲染逻辑成为系统核心的一部分，升级时会跟随主版本一起测试、一起维护。这看起来只是一个“语法支持范围”的变化，实际解决的是知识库内容与团队既有工作流之间的兼容性问题。

从团队协作角度看，这个变化降低了内容维护的交接成本。以前新人学习 DokuWiki 语法是一道必修课，现在如果你已经会 Markdown，进入门槛就低了很多。对于已经有大量 Markdown 文档的团队，迁入 DokuWiki 时不再需要把所有内容重写一遍。

还有一个容易被忽略的信号：大量 AI 编程助手、内容处理工具、自动化脚本都使用 Markdown 作为输入输出格式。知识库如果原生支持 Markdown，未来无论是做内容批量处理、与 Code Repository 联动，还是把 Wiki 页面作为上下文喂给 AI 工具，都会少很多转换损耗。

2. DokuWiki 的底层逻辑与传统语法特点

2.1 DokuWiki 是什么

DokuWiki 是一个用 PHP 编写的开源 Wiki 引擎，最大特征是不依赖数据库，页面内容保存在服务器上的纯文本文件中。它很轻量，单台普通虚拟主机就能跑起来，安装包只有几 MB 级别，部署和备份都相对直接。

它的页面组织方式也与传统 Wiki 有区别。开发者可以按命名空间创建目录层级，配合权限控制实现类似“部门文档区 / 项目文档区 / 公开文档区”的结构。用一套系统承载多团队文档，在中小规模场景中非常常见。

2.2 传统 DokuWiki 语法为何有学习成本

在 Markdown 进入核心之前，DokuWiki 使用的是自己设计的标记语法。这套语法并没有不好，实际上和很多轻量标记语言一样，追求用尽量少的符号表达常用格式。但问题在于：它只在 DokuWiki 体系内有效。

为了理解这次改版的意义，下面用一个表格对比 DokuWiki 标记与标准 Markdown 的差异：

从对比里能直观看到，加粗这种基础语法两边一致，但标题、链接、代码块的差异非常大。老用户可能觉得自家语法更简洁，但新用户从网上复制一段 Markdown 内容放进 DokuWiki，渲染出来的大概率是一片混乱。

2.3 为什么不是“替换”，而是“支持”

如果新版直接强制把所有页面改成 Markdown，老用户的页面会全线崩盘。成熟的 Wiki 系统在格式演进上通常采用兼容策略，也就是新语法与旧语法并存，由配置决定默认解析方式，而不是一刀切重写所有历史内容。

对 DokuWiki 来说，原生化支持 Markdown 更现实的路径是：新页面或者显式声明为 Markdown 的页面走新的解析器，旧页面继续沿用传统语法，等迁移完成后再整体切换。这样既保住了历史资产，也让团队有充足时间制定内容规范。

3. 新版本 Mort 的定位与 PHP 8.2 要求的影响

3.1 版本代号背后的生态信号

DokuWiki 版本的代号有很大概率延续使用奇幻文学作品中的角色名。Mort 这个代号本身就带有“新阶段开启”的叙事意味。而从版本方向看，核心层吸收 Markdown 是一个明确的信号：Wiki 软件不能再把自己封闭在独立语法孤岛上，必须主动融入主流的文档生态。

从插件的处理方式来看，原生支持 Markdown 的更深层影响是：以后可以围绕 Markdown 内容去做链接自动补全、目录生成、全文检索优化等系统级能力，这些能力如果建立在第三方插件之上，很难保证与核心的更新节奏一致。

3.2 PHP 8.2 不是可选升级

如果你是 DokuWiki 老用户，需要特别留意的是 PHP 版本的硬性要求。新版部署环境要求 PHP 8.2 及以上，这意味着那些还运行在 PHP 7.4 或 PHP 8.0 的服务器不能直接平滑升级，必须先处理运行环境。

很多团队的知识库服务器都是“配置完就不动了”的状态，系统里很可能还留着比较老的 PHP 版本。这种情况不能直接在生产环境执行升级，而是应该先在临时环境验证 PHP 兼容性和既有插件可用性，再制定分批切换计划。

从 PHP 官方维护节奏看，PHP 8.1 及更早版本陆续进入安全支持末期，新版 DokuWiki 提高对 PHP 版本的要求也符合整个开源生态主动淘汰旧运行时的趋势。越早完成服务器基础环境升级，后续获得安全更新和功能迭代的成本越低。

4. 部署环境准备：PHP 8.2 与 Web 服务器配置

4.1 Debian/Ubuntu 安装 PHP 8.2

生产服务器建议使用官方软件源或第三方维护的 PPA。以下示例以 Ubuntu/Debian 系为例，配置 PHP 8.2 及 DokuWiki 常用扩展。

sudo apt update sudo apt install -y php8.2 php8.2-fpm php8.2-xml php8.2-mbstring \ php8.2-gd php8.2-zip php8.2-curl php8.2-json

不同操作系统下扩展包名可能有差异。如果你的服务器使用 CentOS/RHEL 系，需要把php8.2-*换成对应的php82-php-*命名，并启用相应的软件源。

安装完成后，验证版本：

php -v php -m | grep -E 'xml|mbstring|gd|zip|curl|json'

确认输出中包含 php8.2 的版本信息，并且上面列出的扩展全部存在。缺少xml或mbstring时，DokuWiki 的解析和国际化处理都会出现异常，不要跳过这一检查步骤。

4.2 Nginx 站点配置与安全边界

DokuWiki 有目录级安全要求。使用 Apache 时，自带的和.htaccess规则可以挡掉部分敏感目录访问。使用 Nginx 时，必须手动配置，否则data、conf等目录存在被直接访问的风险。

下面是一份适合 DokuWiki 的 Nginx 站点配置示例：

server { listen 80; server_name wiki.example.com; root /var/www/dokuwiki; index index.php index.html; charset utf-8; # 禁止访问数据与配置目录 location ~ /(data|conf|bin|inc)/ { deny all; } # 禁止访问备份和临时文件 location ~ /\.(ht|git|svn) { deny all; } # PHP 请求转发到 PHP-FPM location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.2-fpm.sock; } # 静态文件缓存 location ~* \.(css|js|png|jpg|jpeg|gif|svg|ico)$ { expires 7d; add_header Cache-Control "public"; } }

配置完成后执行：

sudo nginx -t sudo systemctl reload nginx

这份配置里最关键的是第一组location规则。不要为了图省事把deny all去掉，否则别人可能直接下载到包含用户会话、页面历史记录的敏感文件。生产环境还应按需打开 HTTPS，避免账号密码和编辑内容明文传输。

5. DokuWiki Mort 版部署与原生 Markdown 能力验证

5.1 获取安装包

DokuWiki 官方提供稳定版打包文件。建议从官方下载页面获取最新版本链接，不要使用不明来源的二次打包。

cd /var/www wget https://download.doku.org/src/dokuwiki-stable.tgz tar -xzf dokuwiki-stable.tgz sudo mv dokuwiki-*/ dokuwiki

安装包解压后，确保运行目录归属于 Web 服务用户：

sudo chown -R www-data:www-data /var/www/dokuwiki

如果后面出现“无法写入 conf 目录”或“无法保存页面”的提示，优先检查这一步权限是否缺失。

5.2 通过安装向导完成初始化

浏览器访问http://你的服务器地址/install.php，按向导填写 wiki 名称、管理员用户名、邮箱和密码。安装完成后，DokuWiki 会提示删除install.php。这一步不要忽略，保留安装脚本会被扫描工具标记为风险项。

删除安装脚本：

sudo rm -f /var/www/dokuwiki/install.php

5.3 验证原生 Markdown 解析是否生效

DokuWiki 原生支持 Markdown 后，最直接的体验差异在于：新创建的页面可以按 Markdown 语法来编写并得到正确渲染。为了验证系统是否按预期工作，可以在 Wiki 后台新建一个测试页面，在内容区输入以下内容：

# 这是 Markdown 一级标题 这是一个**加粗**文本，这是一个 `行内代码`。 ## 二级标题 - 列表项一 - 列表项二 > 这是一段引用。 [跳转到示例站](https://example.com)

保存后，如果页面正确渲染出带一级标题样式的文本、列表和引用块，说明该页面的解析器已经识别并执行了 Markdown 语法。

需要特别提醒：不同版本对 Markdown 的启用范围可能不一样，有的默认全局开启，有的需要针对页面或命名空间单独设置。如果你把上述内容保存后看到一屏幕原始符号而没有任何排版效果，说明你还没有为这个页面/空间开启 Markdown 渲染模式。不要急着怀疑安装失败，先检查后台配置、页面头部标志或官方文档中关于 Markdown 启用范围的说明。

5.4 如何用 Git 维护纯文本页面

DokuWiki 页面存储在data/pages/目录，文件名和路径对应命名空间与页面名。这个特性使得它在版本管理方面很友好。配合 Git 使用，可以做到对内容变更的可追溯。

cd /var/www/dokuwiki/data/pages git init git add -A git commit -m "初始化 Wiki 页面内容"

如果团队有内容审计需求，可以定期通过脚本将变更推送到远端仓库。由于 DokuWiki 页面是纯文本文件，Git 对比阅读 diff 的体验会比其他数据库型 Wiki 好很多。

6. 从传统 DokuWiki 语法迁移到 Markdown 的工程注意点

6.1 迁移不是全局查找替换

看起来这只是把====== 标题 ======改成# 标题，但真实世界里的文档远比示例复杂。很多历史页面中会有特殊插件语法、多媒体嵌入语法、命名空间链接和各种转义写法。无脑执行“左移和符号替换”极有可能产生比原来更糟的排版结果。

更稳妥的思路是先盘点存量页面，再按内容价值决定迁移优先级。那些仍在高频使用的页面优先处理，长期无人访问的历史快照页面可以保持旧语法不动，或者直接归档。

6.2 常见迁移对照参考

下面是一份可作为团队速查表的语法转换清单：

上面表格里的站内链接写法只是参考方向，具体目标地址取决于 Markdown 解析器如何映射 DokuWiki 内部页面 ID。迁移完成后，需要逐个点击验证，确保页面跳转没有断链。

6.3 两种语法并存阶段的坑

混用阶段最常见的错误是：在一个页面里用过后的 Markdown 标题语法，页尾却又留下了 DokuWiki 的<code>代码块标签。解析器遇到不认识的语法时，不同实现策略不一样，有的直接把它当作普通文本输出，有的会把它转义显示。结果往往是页面排版看着正常一部分，又挂着几行多余的标签，用户体验很差。

建议在切换期间为每个页面标识清楚“当前使用的语法类型”，并在编辑摘要里强制填写，避免下一个编辑者看不懂页面结构产生二次污染。如果 wiki 支持命名空间级别的解析器配置，可以按“历史空间”和“新文档空间”做物理隔离，降低内部冲突概率。

6.4 Markdown 与 DokuWiki 命名空间链接的取舍

DokuWiki 页面之间的链接不依赖完整 URL，而是基于页面 ID。Markdown 在处理内部 Wiki 链接时，如果解析器不感知 DokuWiki 的页面 ID 规则，就需要写完整 URL 或特殊标记。从工程实践看，迁移初期不要把内部链接全部改成绝对 URL，否则服务器域名一变，链接会大量失效。优先使用系统提供或社区兼容层支持的站内链接写法，只把通用文本格式切到 Markdown，站内结构仍沿用系统内部识别机制。

7. 常见问题与排查方法

7.1 问题排查表

7.2 为什么“清缓存”经常是第一步

DokuWiki 会缓存渲染后的页面 HTML，提升响应速度。当你切换语法解析器或修改了插件设置后，旧缓存很可能让新配置不生效。这种时候最容易做出错误判断，以为 Markdown 没开启成功。

正确的做法是：先在后台执行缓存清理，或者删除data/cache/下的缓存文件，再重新访问页面验证。如果仍无效果，再检查页面级配置，不要反复重装系统浪费时间。

sudo rm -rf /var/www/dokuwiki/data/cache/*

7.3 升级之前如何备份

基于纯文本存储的 Wiki 备份起来相对容易。至少要备份data/和conf/两个目录，前者包含所有页面和历史版本，后者包含站点配置。

sudo tar -czf dokuwiki-backup-$(date +%Y%m%d).tar.gz \ /var/www/dokuwiki/data \ /var/www/dokuwiki/conf

执行升级前，把这份压缩包复制到独立服务器或对象存储。不要只备份在当前服务器磁盘上，一旦升级过程中误操作覆盖了原目录，备份也会一起丢失。

8. 最佳实践与工程建议

8.1 先建“沙盒命名空间”

在正式迁移大量页面之前，建立一个sandbox或测试命名空间，所有新语法验证都先在里面进行。把从网上摘录的 Markdown 片段粘贴进来，观察渲染效果，确认符合预期后再推广给团队。这比直接改用户高频使用的首页要安全得多。

8.2 给团队一份“语法规约”

如果团队里既有 DokuWiki 老用户又有 Markdown 新人，混用阶段会产生大量内容风格不一致。建议把可接受语法范围写清楚：

• 新页面默认只允许写标准 Markdown。
• 旧页面在迁移完成前不要用编辑器里的“自动格式化”功能整页重排。
• 站内链接优先参考系统兼容说明，不强制写绝对路径。
• 表格统一用 Markdown 表格语法，不必保留旧的表格书写习惯。

8.3 配置代码与页面目录的权限边界

DokuWiki 的内容是文本文件，意味着只要 Web 服务能写data/，攻击者一旦拿到编辑权限，理论上就有可能写入恶意内容。生产环境建议关闭匿名编辑、开启编辑审核，不要为了方便把权限放宽到“所有人可改”。如果知识库不对外开放，可以使用系统防火墙或 Web 服务的访问控制，限定只允许公司内网 IP 访问后台和install.php。

8.4 关注 PHP 8.2 弃用函数对老插件的影响

即使 DokuWiki 核心支持 PHP 8.2，历史遗留的第三方插件未必兼容。升级到 Mort 版本前，建议先梳理当前已经启用的所有插件，逐个确认其是否适配 PHP 8.2 和新的 Markdown 渲染逻辑。对于多年未更新、已经找不到维护者的插件，应尽早寻找替代方案并替换，而不是让它在核心升级后继续拖累整体稳定性。

8.5 将“内容格式统一”作为一个独立事项推进

很多团队升级 Wiki 时只关注版本号和服务器配置，没有把“用哪种语法承载内容”当做一个工程决策来对待。实际上，这次 DokuWiki 的版本更新恰好是一个重新整理内容规范的时机。如果条件允许，可以同时在团队内部启用编辑模板，把常用文档结构，比如故障报告、周报、技术方案评审，预设成 Markdown 模板。这样既能让内容格式统一，也能减少使用者面对空白页时的写作阻力。

9. 结语与后续关注点

DokuWiki 新版把 Markdown 支持下放到核心层，是 Wiki 类软件顺应内容生态的一次重要变化。它降低了新用户的上手门槛，也让存量文档在格式层面更容易与现代化工具链融合。与此同时，PHP 8.2 的部署要求也提醒所有维护者：知识库这类“稳定优先”的系统，也需要定期跟进底层运行时的维护节奏，不能因为“还能用”就一直拖到安全风险不可控。

对于想尝鲜的读者，下一步可以准备一台临时服务器，安装 PHP 8.2 和最新版 DokuWiki，在一个独立命名空间里尝试用 Markdown 新建几篇页面，对比这套语法体验和传统写法在运维、编辑、团队协作上的差别。如果你的团队已经有大量历史 DokuWiki 页面，不要急着做全局切换，先把沙盒命名空间和备份策略建好，再从边缘项目页面开始渐进迁移。

如果你的团队正在犹豫是否把知识库迁到 DokuWiki，或者纠结站内历史页面怎么平稳过渡到 Markdown，可以先从这篇里的部署步骤和迁移清单入手。建议收藏备用，等到真正操作的时候，把前四个章节当部署手册，把第六到第八章节当排障和复盘清单。

内容格式的迁移永远不只是字符替换，它本质上是团队协作方式和信息流通规则的再定义。祝迁移顺利。