XAMPP 环境下安装 Moodle 在线教育系统的环境检查修复-php教程-PHP中文网

moodle安装失败主因是php扩展缺失、mysql字符集不兼容、apache rewrite模块未启用及data目录权限不足；需依次启用curl/mbstring/xml/zip/gd扩展，设mysql默认字符集为utf8mb4，开启mod_rewrite并设allowoverride all，配置独立可写dataroot路径。

xampp 环境下安装 moodle 在线教育系统的环境检查修复

PHP 扩展缺失导致 Moodle 安装卡在环境检查页

Moodle 要求 curl、mbstring、xml、zip、gd 等扩展必须启用，XAMPP 默认可能只启用了基础模块。访问 http://localhost/moodle/admin/environment.php 时若看到红叉或“Not available”，不是 Moodle 问题，而是 PHP 配置未生效。

实操建议：

打开 XAMPP 控制面板 → Apache 行右侧的 Config → 选 PHP (php.ini)
搜索 ;extension=mbstring，去掉分号取消注释；同理处理 ;extension=curl、;extension=gd、;extension=zip、;extension=xml（注意：XAMPP 8.0+ 使用 php_zip.dll，旧版可能是 php_zip.dll 或 php_zip.dll，路径需与 extension_dir 一致）
确认 extension_dir 指向正确目录，例如 C:\xampp\php\ext（Windows）或 /Applications/XAMPP/xamppfiles/lib/php/extensions/no-debug-non-zts-20220829/（macOS）
保存后重启 Apache —— 不重启不会加载新扩展

MySQL 字符集不兼容引发安装中途报错

Moodle 要求数据库默认字符集为 utf8mb4，而 XAMPP 自带 MySQL 5.7+ 默认是 utf8mb4，但部分旧版或手动修改过配置的实例仍用 latin1 或 utf8（非完整 UTF-8），会导致安装到“创建数据库表”阶段抛出 Specified key was too long 或 Incorrect string value 错误。

实操建议：

编辑 C:\xampp\mysql\bin\my.ini（Windows）或 /Applications/XAMPP/xamppfiles/etc/my.cnf（macOS）

在 [mysqld] 下添加：

character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb_file_format = Barracuda
innodb_file_per_table = 1
innodb_large_prefix = 1

在 [client] 和 [mysql] 下各加一行：default-character-set = utf8mb4
重启 MySQL 服务，并登录验证：mysql -u root -p -e "SHOW VARIABLES LIKE 'character_set%';"，确保所有相关项均为 utf8mb4

Apache rewrite 模块未启用导致 Moodle 登录后 404

Moodle 启用 SEO 友好 URL（即去除 index.php?）后，依赖 Apache 的 mod_rewrite。XAMPP 默认关闭该模块，表现为：首页可访问，但点击“登录”或进入课程后跳转地址变成 http://localhost/course/view.php?id=2 却返回 404 —— 实际是路由重写失败，Apache 直接尝试找物理文件。

实操建议：

打开 httpd.conf（通过 XAMPP 控制面板 → Apache → Config → Apache (httpd.conf)）
搜索 #LoadModule rewrite_module modules/mod_rewrite.so，去掉开头的 #
再搜索 <directory></directory>（Windows）或对应 htdocs 路径段，将其中的 AllowOverride None 改为 AllowOverride All
保存并重启 Apache
确认 Moodle 管理后台 → Site administration › Server › HTTP 中 “Use mod_rewrite” 已勾选（此项需先完成上一步才可启用）

data 目录权限不足或路径错误导致安装无法写入

Moodle 要求 dataroot 目录（非 Web 可访问路径）具备完整读写权限，且不能放在 htdocs 内。XAMPP 用户常误将 $CFG->dataroot 设为 C:\xampp\htdocs\moodledata，结果安装时提示 Cannot write to data directory 或后续上传头像、课件失败。

实操建议：

在 config.php 中显式定义 $CFG->dataroot，例如：

$CFG->dataroot  = 'C:\xampp\moodledata'; // Windows<br>$CFG->dataroot  = '/Applications/XAMPP/xamppfiles/moodledata'; // macOS

手动创建该目录，并赋予当前系统用户完全控制权（Windows 右键属性 → 安全 → 编辑；macOS 执行 sudo chown -R $(whoami) /Applications/XAMPP/xamppfiles/moodledata）
确保该路径不在任何 Web 根目录下，Apache 无法通过 URL 访问到它（可用浏览器直接请求 http://localhost/moodledata 测试是否 403 或 404）
若使用 Windows，避免路径含中文或空格；若用 macOS，注意 SIP 对 /System 等路径的限制，务必选 XAMPP 安装目录内或用户主目录下的位置

Moodle 对 PHP 扩展、MySQL 字符集、Apache 模块和文件系统权限这四点极为敏感，任意一项不到位都会在不同阶段中断流程 —— 环境检查页、数据库初始化、URL 路由、数据写入，每个环节背后其实只绑定一个具体配置项。修的时候别猜，对着报错信息反查对应模块，比重装 XAMPP 有效得多。