MediaWiki开发者环境搭建与使用指南

MediaWiki开发者环境搭建与使用指南

mediawiki 🌻 The collaborative editing software that runs Wikipedia. Mirror from https://gerrit.wikimedia.org/g/mediawiki/core. See https://mediawiki.org/wiki/Developer_access for contributing. 项目地址: https://gitcode.com/gh_mirrors/me/mediawiki

前言

MediaWiki作为一个知名的开源Wiki系统，是许多知识共享平台背后的核心引擎。对于开发者而言，搭建一个本地的开发环境是参与MediaWiki开发的第一步。本文将详细介绍如何基于Docker搭建MediaWiki开发环境，并解决开发过程中可能遇到的常见问题。

开发环境概述

MediaWiki提供了一个基于Docker Compose的可扩展本地开发环境，包含以下核心组件：

• PHP运行环境
• Apache Web服务器
• Xdebug调试工具
• SQLite数据库

重要提示：此开发环境仅用于本地开发测试，切勿用于生产环境！

环境准备

系统要求

1. Docker安装：

   • macOS/Windows用户：安装Docker Desktop
   • Linux用户：安装Docker引擎及相关组件

2. 各系统特殊配置：

   • Windows用户：建议启用WSL2以获得更好的性能
   • Mac用户：Apple Silicon芯片需注意Rosetta兼容性问题
   • Linux用户：需配置非root用户权限

环境搭建步骤

1. 获取MediaWiki源码

通过Git获取最新代码：

git clone https://gerrit.wikimedia.org/r/mediawiki/core.git mediawiki

2. 配置环境变量

在项目根目录创建.env文件，内容如下：

MW_SCRIPT_PATH=/w
MW_SERVER=http://localhost:8080
MW_DOCKER_PORT=8080
MEDIAWIKI_USER=Admin
MEDIAWIKI_PASSWORD=dockerpass
XDEBUG_CONFIG=
XDEBUG_ENABLE=true
XHPROF_ENABLE=true

根据操作系统不同，还需添加用户权限配置。

3. 启动容器

执行以下命令启动开发环境：

docker compose up -d

4. 安装依赖

安装PHP依赖：

docker compose exec mediawiki composer update

5. 初始化MediaWiki

执行安装脚本：

docker compose exec mediawiki /bin/bash /docker/install.sh

完成以上步骤后，即可通过http://localhost:8080访问本地Wiki。

开发环境使用技巧

常用操作命令

1. 进入容器Shell：

   docker compose exec mediawiki bash
   

2. 执行维护脚本：

   docker compose exec mediawiki php maintenance/run.php update
   

测试相关

1. PHPUnit测试：

   docker compose exec mediawiki bash
   cd tests/phpunit
   composer phpunit -- path/to/test/
   

2. Selenium测试： 需配置专用容器运行前端测试。

扩展管理

以安装Vector皮肤为例：

1. 克隆皮肤仓库：

   cd skins/
   git clone https://gerrit.wikimedia.org/r/mediawiki/skins/Vector
   

2. 在LocalSettings.php中启用：

   wfLoadSkin( 'Vector' );
   

高级配置

Xdebug调试

默认需要触发条件启动调试，可通过以下方式配置：

1. 浏览器安装Xdebug扩展控制调试会话
2. 或设置环境变量自动启动：

   XDEBUG_CONFIG=start_with_request=yes
   

自定义开发环境

通过docker-compose.override.yml文件可覆盖默认配置，常见用例包括：

• 挂载本地扩展目录
• 配置额外服务
• 调整Xdebug参数

修改后需重启容器生效：

docker compose down
docker compose up -d

故障排除

常见问题解决方案

1. 缓存问题： 在LocalSettings.php中禁用各类缓存：

   $wgMainCacheType = CACHE_NONE;
   // 其他缓存配置...
   

2. 数据库连接错误：

   • 检查SQLite目录权限
   • 确认LocalSettings.php中的路径配置正确

3. Xdebug无法连接：

   • Linux用户需配置host.docker.internal
   • 检查端口配置（Xdebug 3.x默认使用9003端口）

日志收集

启用Xdebug远程日志：

XDEBUG_CONFIG=remote_log=/tmp/xdebug.log

环境维护

1. 暂停环境：

   docker compose stop
   

2. 重建环境：

   docker compose down
   docker compose up -d
   

3. 重置数据库：

   • 删除LocalSettings.php和sqlite缓存目录
   • 重新运行安装脚本

结语

本文详细介绍了MediaWiki开发环境的搭建和使用方法，涵盖了从基础配置到高级调试的各个方面。通过Docker化的开发环境，开发者可以快速搭建、灵活配置，并高效地进行MediaWiki的开发和测试工作。遇到问题时，参考故障排除部分通常能找到解决方案。随着对环境的熟悉，开发者可以进一步探索MediaWiki的强大功能和扩展机制。

mediawiki 🌻 The collaborative editing software that runs Wikipedia. Mirror from https://gerrit.wikimedia.org/g/mediawiki/core. See https://mediawiki.org/wiki/Developer_access for contributing. 项目地址: https://gitcode.com/gh_mirrors/me/mediawiki