RedmineX安装执行rake插件迁移报cannot load such file错误

API 探路者

2026-9-3

服务器运行环境

ruby      3.0.4-p208
passenger 6.0.14
redmine   5.0.1.stable
redmineUP 所有插件最新版本
mysql2    5.7

故障现象

已完成redmineUP安装，基础功能运行正常，本次安装的RedmineX插件官方标注兼容当前环境、依赖redmineUP组件
执行插件数据库迁移命令时执行失败，执行的命令为：

bundle exec rake redmine:plugins:migrate RAILS_ENV=redmine_test

核心报错为cannot load such file -- redmine_x_ux_upgrade/view_projects_hook (LoadError)，完整报错栈如下：

cannot load such file -- redmine_x_ux_upgrade/view_projects_hook (LoadError)
  /home/test_user/.gem/ruby/3.0.4/gems/zeitwerk-2.5.4/lib/zeitwerk/kernel.rb:35:in `require'
  /home/test_user/.gem/ruby/3.0.4/gems/zeitwerk-2.5.4/lib/zeitwerk/kernel.rb:35:in `require'
  /home/test_user/.gem/ruby/3.0.4/gems/activesupport-6.1.6/lib/active_support/dependencies/zeitwerk_integration.rb:51:in `require_dependency'
  /home/test_user/redmine-5.0.1/plugins/000_redmine_x_ux_upgrade/init.rb:22:in `<top (required)>'
  /home/test_user/redmine-5.0.1/lib/redmine/plugin_loader.rb:31:in `load'

GEM PATHS:
  - /home/test_user/.gem/ruby/3.0.4
  - /opt/rubies/ruby-3.0.4/lib/ruby/gems/3.0.0

已确认报错提示缺失的文件实际存在，存储路径为：

/home/test_user/redmine_test/plugins/000_redmine_x_ux_upgrade/lib/redmine_x_ux_upgrade/view_projects_hook.rb

已尝试将/home/test_user/redmine_test/、/home/test_user/redmine_test/plugins/加入GEM_PATH配置，故障未解决。

故障根因

插件存放路径与Redmine实际加载路径不匹配：报错栈明确显示Rake任务加载插件的根目录是/home/test_user/redmine-5.0.1/plugins/，但RedmineX插件实际被放在了/home/test_user/redmine_test/plugins/目录下，两个是完全独立的Redmine部署目录，加载路径下不存在对应插件文件，自然无法找到依赖文件。
RAILS_ENV参数配置错误：Redmine官方默认支持的运行环境只有production（生产环境）、development（开发环境）、test（测试环境）三个值，传入自定义的redmine_test值没有对应数据库配置、应用初始化配置，会触发加载逻辑异常。
GEM_PATH修改操作无效：Redmine启动时会自动将当前部署目录下plugins/*/lib路径加入自动加载队列，不需要手动将插件路径加入GEM_PATH，添加错误的根目录反而会干扰正常加载逻辑。

解决方案

按以下顺序操作：

确认要部署RedmineX的目标Redmine目录，将/home/test_user/redmine_test/plugins/下的000_redmine_x_ux_upgrade整个插件目录，完整复制/移动到/home/test_user/redmine-5.0.1/plugins/目录下，保证与报错栈中加载init.rb的路径匹配。注意：不要修改插件原目录名000_redmine_x_ux_upgrade，否则会触发Zeitwerk自动加载规则匹配失败。
还原之前错误修改的GEM_PATH配置，删除手动添加的两个Redmine相关路径，避免干扰RubyGems正常加载逻辑。
进入正确的Redmine部署目录，使用正确的环境参数执行迁移命令，生产环境部署使用production参数即可：

cd /home/test_user/redmine-5.0.1/
bundle exec rake redmine:plugins:migrate RAILS_ENV=production

迁移执行完成后，触发Passenger重启让插件生效：

touch /home/test_user/redmine-5.0.1/tmp/restart.txt

如果仍报加载错误，检查插件目录权限，保证运行Redmine/Passenger的用户对插件整个目录有读权限：

chown -R 运行Redmine的用户:运行Redmine的用户组 /home/test_user/redmine-5.0.1/plugins/000_redmine_x_ux_upgrade/
chmod -R 755 /home/test_user/redmine-5.0.1/plugins/000_redmine_x_ux_upgrade/

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