生产服务器上Composer无法自动加载/src目录文件的问题排查

问题描述 #

本地环境运行正常，但生产服务器上Composer无法自动加载/src目录下的文件，报错提示找不到路径：/home/customer/www/example.com/public_html/wp-content/plugins/example-plugin/vendor/composer/../../src/Commands/Example_Commands.php，但该文件实际存在。已尝试在本地删除/vendor目录与composer.lock文件，执行composer dump-autoload和composer install --no-dev命令后上传至生产服务器，问题仍未解决。

项目目录结构 #

resources
src
- Commands
  - Example_Commands.php
- Other_Class.php
- Another_Class.php
vendor
- composer
  - ..other composer files
  - autoload_real.php
- ..other packages
composer.json
composer.lock
plugin-index.php

composer.json配置 #

{
  "require": {
    "illuminate/encryption": "^9.33",
    "wp-cli/wp-config-transformer": "^1.3",
    "azurre/php-simple-logger": "^1.1"
  },
  "autoload": {
    "files": [
      "src/User.php",
      "src/Utils.php",
      "src/Config_Checker.php",
      "src/Admin_Notices.php",
      "src/ACF.php",
      "src/Commands/Example_Commands.php",
      "src/Service_Logic.php",
      "src/Cron.php",
      "src/Email.php"
    ]
  }
}

加载代码（plugin-index.php） #

require_once(plugin_dir_path(__FILE__) . 'vendor/autoload.php');

排查与解决办法 #

1. 检查文件名大小写匹配 #

Linux服务器严格区分文件名大小写，而Windows/macOS默认不区分。需确认服务器上src/Commands/Example_Commands.php的文件名、目录名与composer.json中的配置完全一致，避免出现commands或example_commands.php这类大小写差异。

2. 直接在生产服务器执行Composer命令 #

本地生成的自动加载文件可能包含环境相关路径，建议直接在服务器上操作：

• 上传项目文件（排除vendor和composer.lock）到服务器
• SSH登录服务器，进入插件目录：

  cd /home/customer/www/example.com/public_html/wp-content/plugins/example-plugin
  

• 执行安装命令并优化自动加载：

  composer install --no-dev --optimize-autoloader
  

3. 修复文件权限 #

确保src目录及下属文件的权限符合服务器运行要求：

• 设置目录权限为755，文件权限为644：

  chmod -R 755 src/
  chmod -R 644 src/*.php src/Commands/*.php
  

• 确认服务器运行用户（如www-data）对这些文件拥有读取权限。

4. 校验composer.json路径配置 #

检查autoload.files中的路径是否与实际文件完全匹配，比如项目目录中未列出src/User.php，需确认该文件是否存在，避免路径拼写错误。

5. 验证自动加载映射文件 #

查看服务器上vendor/composer/autoload_files.php，搜索Example_Commands.php对应的条目，确认生成的路径是否能正确指向实际文件。

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