Composer 安装与使用教程（PTAdmin 环境）

Composer 是 PHP 项目的依赖管理工具。PTAdmin 使用 Composer 安装 Laravel 框架、PTAdmin 组件和项目所需的 PHP 扩展，因此在执行 PTAdmin 安装前，应先确认命令行 PHP 和 Composer 环境正常。

本文适用于宝塔面板 Linux 环境，也适用于没有宝塔面板的 Linux 服务器。Windows 用户可以参考 Composer 官方下载页 安装。

适用范围说明：本文的 Composer 安装和项目依赖命令适用于使用 Bash 或兼容 Shell 的主流 Linux 发行版，包括 Debian/Ubuntu、CentOS/RHEL、Rocky Linux/AlmaLinux、openEuler、Alibaba Cloud Linux 及宝塔 Linux。不同发行版安装 PHP、PHP 扩展和 Web 服务的命令可能不同，本文不替代对应发行版的系统安装文档。

文中 /www/server/php/81/bin/php 是宝塔 PHP 8.1 的示例路径，普通 Linux 不应直接照抄。请使用 php -v 检查命令行 PHP，或替换为服务器实际 PHP 路径。PTAdmin 是否能安装，最终以当前版本的 PHP、扩展要求和 composer.lock 为准。

一、安装前先确认 PHP 环境

Composer 使用的是命令行 PHP。宝塔网站绑定的 PHP 版本与终端中的 PHP 版本可能不同，所以不要只看网站设置中的版本，先在终端检查实际命令。

php -v
php --ini
command -v php
command -v composer

PTAdmin 项目当前的依赖声明要求 PHP 7.4 或 8.x，并要求启用 gd、json、mbstring、openssl、pdo 和 zip 等扩展。具体版本还要以你要安装的 PTAdmin 版本及其 composer.lock 为准。

PHP 7.4 已停止官方安全维护。新部署建议选择项目实际兼容且仍受安全维护的 PHP 8.x 版本，并让命令行 PHP 与网站运行 PHP 保持一致。

二、宝塔面板 Linux 环境安装 Composer

登录宝塔面板，打开左侧的“终端”，进入服务器后执行下面的命令。命令使用 Composer 官方安装器，并在安装前校验安装脚本的 SHA-384 签名。

cd /tmp

EXPECTED_CHECKSUM="$(php -r 'copy("https://composer.github.io/installer.sig", "php://stdout");')"
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"

if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
    echo '安装脚本校验失败'
    rm -f composer-setup.php
    exit 1
fi

php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm -f composer-setup.php
composer --version

看到 Composer 版本号，说明安装成功。这里使用了 --install-dir=/usr/local/bin 和 --filename=composer，安装完成后可以在任意目录直接执行 composer。

如果当前终端用户没有权限写入 /usr/local/bin，请使用具有管理员权限的终端安装，或把 Composer 安装到当前用户自己的 PATH 目录。

三、没有宝塔面板时的 Linux 安装方式

纯 Linux 服务器也可以在临时目录中执行相同的官方安装流程。安装完成后，确认 composer 所在目录已经加入当前用户的 PATH。

mkdir -p "$HOME/bin"
cd /tmp

EXPECTED_CHECKSUM="$(php -r 'copy("https://composer.github.io/installer.sig", "php://stdout");')"
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"

if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
    echo '安装脚本校验失败'
    rm -f composer-setup.php
    exit 1
fi

php composer-setup.php --install-dir="$HOME/bin" --filename=composer
rm -f composer-setup.php
export PATH="$HOME/bin:$PATH"
composer --version

如果希望所有用户都能调用 Composer，可以由管理员将生成的文件放入系统 PATH 目录。安装文件属于可执行程序，请确认目标目录和文件权限后再操作。

四、配置 Composer 镜像（按需使用）

如果访问 Packagist 官方源速度较慢或经常超时，可以尝试配置 阿里云 Composer 镜像。镜像可能存在同步延迟，遇到某个版本找不到时，可以暂时撤销镜像设置后再排查。

# 全局配置：影响当前系统用户的所有 Composer 项目
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 项目配置：只影响当前项目
composer config repo.packagist composer https://mirrors.aliyun.com/composer/

# 撤销项目级镜像
composer config --unset repo.packagist

# 撤销当前用户的全局镜像
composer config -g --unset repo.packagist

-g 只影响当前系统用户的全局配置，并不代表服务器上的所有用户。生产服务器如果由专门的部署用户执行 Composer，建议使用项目级配置，避免不同项目之间互相影响。

五、在 PTAdmin 项目中安装依赖

必须先进入包含 composer.json 的 PTAdmin 项目根目录，再执行安装命令：

cd /你的PTAdmin项目路径
composer install --no-dev --optimize-autoloader

如果项目中已经存在 composer.lock，composer install 会按锁定版本安装，适合部署环境保持依赖一致。不要把 composer update 当成安装失败的常规解决办法，因为它会重新解析并更新依赖版本。

正式环境通常使用 --no-dev 跳过开发依赖，使用 --optimize-autoloader 优化自动加载器。开发环境可以省略 --no-dev。

宝塔中指定网站使用的 PHP 版本

如果终端中的 php -v 不是网站实际使用的版本，请使用对应 PHP 的绝对路径。下面以宝塔 PHP 8.1 为例，81 请根据服务器实际安装的版本调整：

/www/server/php/81/bin/php /usr/local/bin/composer install --no-dev --optimize-autoloader

Composer 本身也应使用同一套 PHP 环境验证。例如，可以先执行 /www/server/php/81/bin/php -v，确认版本和扩展加载情况。

六、宝塔环境常见问题

1. PHP 版本不匹配

网站使用的 PHP-FPM 版本和终端默认 PHP 版本可能不同。先使用 php -v、php --ini 检查 CLI 配置，再改用对应版本的绝对路径执行 Composer。

2. 提示函数被禁用

如果报错涉及 putenv、proc_open 或 symlink，先查看命令行 PHP 实际加载的配置文件和禁用函数：

php --ini
php -r "echo ini_get('disable_functions'), PHP_EOL;"

根据具体错误，仅调整当前安装所需的函数。CLI PHP 与网站 PHP-FPM 可能使用不同的配置文件，修改 CLI 配置后重新执行命令即可，不需要为了 CLI 检查重启 PHP-FPM。

3. 权限不足

先确认执行 Composer 的用户、项目目录所有者和报错的具体路径。不要直接对整个项目执行 chmod -R 755，因为这不能修复所有者错误，还可能让普通文件被设置为可执行。

Laravel 项目通常需要确保 storage 和 bootstrap/cache 可由网站运行用户写入。应根据宝塔站点实际运行用户设置目录所有者和权限，避免使用 root 生成一批普通用户无法维护的项目文件。

4. Composer 被禁止以 root 用户运行

Composer 安装和更新会加载依赖包插件或执行项目脚本，官方不建议长期以 root 用户运行。生产环境应使用站点部署用户执行项目依赖安装；如果确实在隔离环境中以 root 操作，应了解相关风险并确认这是有意行为。

七、安装后的环境检查

安装完成后，可以执行下面的命令检查 Composer 诊断结果、项目平台依赖和已加载扩展：

composer diagnose
composer check-platform-reqs --no-dev
php -m

composer check-platform-reqs --no-dev 会根据当前环境检查生产依赖所需的 PHP 版本和扩展。若提示缺少扩展，应优先在宝塔 PHP 管理中安装对应扩展，再重新检查。

八、部署前检查清单

• 命令行 PHP 版本与 PTAdmin 项目要求一致。
• php --ini 指向了预期的 CLI 配置文件。
• composer -V 能输出 Composer 版本。
• 项目根目录中存在 composer.json，并优先保留项目提供的 composer.lock。
• 项目需要的 PHP 扩展已经启用。
• storage 和 bootstrap/cache 由网站运行用户可写。
• 生产环境按需要使用 composer install --no-dev --optimize-autoloader。
• Composer 镜像配置仅在需要时启用，遇到同步问题可以撤销。

如果安装后遇到网站 404、伪静态或运行目录问题，请继续参考 PTAdmin 伪静态配置教程，并确认站点根目录指向项目的 public 目录。