如何解决Moodle插件卡在“待安装”状态无法完成安装的问题

• 目录权限校验：优先检查Moodle代码目录、moodledata目录的所属用户与权限，80%以上卡待安装的问题都是web服务运行用户（常见为www-data、nginx、apache）对目录无写入权限，导致安装脚本无法写入临时文件、执行数据库变更。重点确认moodledata/temp/、moodledata/cache/两个目录的写入权限是否正常。
• 残留安装锁检查：Moodle安装/升级进程启动时会在数据库写入运行锁，进程异常中断时锁不会自动释放，会阻塞后续所有安装任务。可执行SQL查询锁状态：SELECT value FROM mdl_config WHERE name = 'upgraderunning';，如果返回值为1，说明存在未释放的残留锁。同时可查看mdl_upgrade_log表，确认是否有之前中断的安装任务记录。
• 运行日志排查：查看PHP错误日志（php-fpm或apache/nginx的错误日志文件）、Moodle调试日志（可临时开启调试模式，在站点管理-开发-调试页面查看），确认是否有PHP执行超时、内存溢出、数据库锁冲突、函数不兼容的报错。
• 版本兼容性校验：确认待安装插件的版本要求和当前Moodle主程序版本、PHP版本完全匹配，部分插件版本声明不规范时，会卡在版本校验环节，前端不会抛出可见报错。

所有操作前请先备份整站数据库、Moodle代码目录与moodledata目录，避免操作失误导致站点故障。

• 清理异常状态：先删除moodledata/cache/、moodledata/temp/目录下的所有缓存、临时文件；如果查到存在残留的upgraderunning锁，执行SQL释放：UPDATE mdl_config SET value = 0 WHERE name = 'upgraderunning';
• 优先使用CLI脚本执行安装（无web端超时限制，报错信息更明确）：切换到Moodle站点根目录，以web服务运行用户身份执行命令行升级脚本：

# 以www-data用户为例，根据自己的服务器web用户调整
sudo -u www-data php admin/cli/upgrade.php --non-interactive

脚本会自动执行所有待完成的插件安装、数据库结构升级操作，执行过程中出现的错误会直接打印在终端，可根据报错直接定位问题。

• 若CLI执行仍异常，重置插件状态后重装：先在插件检查页面点击取消安装，删除对应插件目录下的所有文件（插件会存放在mod/、local/、auth/等对应插件类型的目录下），执行缓存清理命令：

sudo -u www-data php admin/cli/purge_caches.php

缓存清理完成后重新上传插件压缩包、正确解压后，再次执行上述CLI升级脚本即可完成安装。

内容的提问来源于stack exchange，提问作者lcdservices