为现有网站添加 Composer

06/10/2025, by Ivan

在 Drupal 8.8.0 中简化

注意：如果您从 Drupal 8.8.0 或更高版本开始构建项目，您的网站已经使用了正确的文件结构，并且已准备好转换为使用 Composer 管理。

本页是一个分步指南，教您如何在以前未使用 Composer 安装的现有网站上手动添加 Composer 支持。如果您是从压缩包手动安装 Drupal 8，或使用了已弃用的 Composer 模板（如 drupal/drupal），此指南适用于您。

适用于基于 Drupal 8.8.0 或更新版本的网站

即使您是通过压缩包安装的 Drupal 8.8.0，Composer 也已预先配置好。因此，您应该可以直接使用 Composer 管理网站，而无需进行额外的转换步骤。

适用于 Drupal 8.8.0 之前创建的网站

在 Drupal 8.8.0 之前，从 https://www.drupal.org/download 下载的压缩包所附带的 composer.json 文件并不适合用于 Composer 管理的网站。

如果您想从手动管理切换到使用 Composer 来安装和更新 Drupal 核心及扩展模块，则需要先修改网站的 composer.json 文件。

以下是一些常见的 Composer 错误信息，表明 composer.json 文件配置错误：

Nothing to install or update (even though updates exist)
Installation request for drupal/drupal No version set (parsed as 1.0.0) -> satisfiable by drupal/drupal[No version set (parsed as 1.0.0)].
don't install drupal/core 8.x.x | remove drupal/drupal No version set (parsed as 1.0.0)
Your requirements could not be resolved to an installable set of packages.

有时，可以通过删除 composer.lock 文件和 vendor/ 目录后重新运行 Composer 更新命令来解决 Composer 模板问题，但将现有的 Drupal 8 网站转换为官方推荐的 Composer 模板项目（请参阅 3.5. 使用 Composer 下载和更新文件）会更加稳定可靠。

工具 gocomposer 和 composerize-drupal 可以尝试自动将旧网站转换为 Composer 项目，但即使是手动转换，对大型网站来说也很简单，不需要太多时间。

完成此过程后，您的项目将具有推荐的目录结构。Composer 配置文件（composer.json、composer.lock 等）、Drush 和 vendor 目录将位于 webroot 之外。原来的网站根目录将包含一个新的 web/ 文件夹，实际网站文件位于其中。如果您的项目目前使用不同的目录布局，您需要更新 Web 服务器配置以指向新的 web/ 目录。我们稍后会回到这一点。

简要步骤（TL;DR）

使用 Composer 当前模板在新目录中安装一个新的 Drupal 网站。
将所有自定义主题、模块、文件和配置复制到新项目中。（务必检查目录结构。）
将旧网站的 settings 设置迁移到新项目中。
在新的 composer.json 中添加所有使用的模块并运行 composer install。
更新数据库并清理缓存（drush updb; drush cr）。
更新 Web 服务器配置。

完整步骤

假设现有网站位于 /var/www/sites/html/ 目录，新网站将创建在 /var/www/sites/new_html/ 目录下。根据您的实际路径进行调整。

开始之前

如果您准备“composer 化”旧网站，那么该网站的核心和 contrib 模块可能并非最新版本。如果您严格按照本指南操作，Drupal 核心和所有模块将更新到最新版本。这通常是您想要的结果，但请考虑您网站的配置。如果您的网站依赖于旧版库或模块，可能需要保持这些旧版本。

如果您希望更新所有内容到最新版本，直接按照本指南操作即可，完成后再解决任何可能出现的问题。更新完成后，您可能会看到一些错误或警告信息。只需根据错误提示搜索修复方案即可。

如果您希望保留原始版本，稍后再使用 Composer 进行更新，请确保安装的 Drupal 核心和模块版本与旧站点一致。请参考 composer create-project 的用法，以了解如何下载特定版本的核心或特定版本的模块。在运行 composer create-project 或 composer require 时务必明确指定版本号（例如 composer require vendor/package:version）。

1. 安装新的 Drupal 网站

从 drupal/recommended-project 模板创建新项目：

cd /var/www/sites
composer create-project drupal/recommended-project:~8.8.0 new_html --stability dev --no-interaction

这将在当前目录下创建 new_html/ 文件夹，其中包含 vendor、web（即 webroot）以及 composer.json 等文件。如果您的旧项目未使用此目录结构，您可以适应这种新结构，以便直接从该目录运行 drush 和 composer。

过去推荐使用 drupal-composer/drupal-project 模板，现在已被官方维护的 drupal/recommended-project 取代。

2. 将文件复制到新的 Composer 项目

注意：以下步骤仅适用于在 Drupal 8.8.0 之前创建的网站。

如果您的项目创建于 Drupal 8.8.0 之前，现在需要复制自定义模块、主题和库到新项目。确保将文件放在新项目中的正确路径下，因为旧的目录结构可能不同。

正确的路径可在 composer.json 的 installer-paths 部分找到：

"extra": {
  "installer-paths": {
    "web/core": ["type:drupal-core"],
    "web/libraries/{$name}": ["type:drupal-library"],
    "web/modules/contrib/{$name}": ["type:drupal-module"],
    "web/profiles/contrib/{$name}": ["type:drupal-profile"],
    "web/themes/contrib/{$name}": ["type:drupal-theme"],
    "drush/Commands/{$name}": ["type:drupal-drush"]
  }
}

旧网站的模块可能位于 /var/www/sites/html/modules/，新网站应放在 /var/www/sites/new_html/web/modules/。

自定义主题：/var/www/sites/new_html/web/themes/custom/
自定义模块：/var/www/sites/new_html/web/modules/custom/
库文件：/var/www/sites/new_html/web/libraries/
上传文件与图片：/var/www/sites/new_html/web/sites/default/files/

确保 Web 服务器对 files 目录具有写入权限。详情可参阅文件权限与所有权安全。

# 设置文件夹所有者
sudo chown -R vftp:www-data /var/www/sites/new_html/web/sites/default/files

# 允许 Web 服务器用户组访问文件目录
sudo find /var/www/sites/new_html/web/sites/default/files -type d -exec chmod u=rwx,g=rwx,o= '{}' \;

# 允许 Web 服务器用户组修改文件
sudo find /var/www/sites/new_html/web/sites/default/files -type f -exec chmod u=rw,g=rw,o= '{}' \;

files 文件夹包含所有用户上传的文件以及临时文件（如缓存的 CSS、JS、模板等）。

如果您复制了这些临时文件夹（如 php/、js/、styles/、css/），请务必手动删除它们。这些文件会在您清理缓存（drush cr）并访问网站后自动重新生成。

3. 迁移 settings.php 到新项目

从旧网站的 settings.php 文件中复制数据库连接信息和相关配置，如 $databases['default']['default']、$settings['hash_salt']、$settings['trusted_host_patterns'] 等。检查两个 settings.php 文件，确认需要迁移的部分。

确保 $config_directories['sync'] 指向有效路径，最好位于 webroot 之外。该目录需对 Web 服务器用户可写。

此外，不要忘记复制 settings.local.php 与 development.services.yml 文件。

4. 将模块添加到新的 Composer 配置

现在需要将网站使用的所有模块添加到新的 composer.json 文件中。

可以手动编辑 composer.json，也可以通过 composer require 命令安装模块。

4.1 获取网站模块列表

如果旧网站未使用 Composer 管理，旧的 composer.json 文件不会列出模块。此时请手动收集所有 contrib 模块的目录名称，并在 composer.json 中添加，例如 modules/contrib/devel/ 对应 drupal/devel。

4.2 手动编辑 composer.json

打开新项目根目录（例如 /var/www/sites/new_html）的 composer.json，将旧文件中 “require” 和 “require-dev” 部分的包复制过来。请自行确认正确的模块版本。

4.3 使用 composer require 安装模块

推荐方法：使用 composer require drupal/<module_name> 安装模块，例如：

composer require drupal/pathauto drupal/token drupal/metatag

使用 composer require --dev drupal/<module_name> 可将模块添加到 require-dev 部分。

4.4 运行 Composer 安装

在项目目录下运行：

composer install

这将下载所有在 composer.json 中列出的模块。若出现问题，可删除 composer.lock 和 vendor/ 后重试。

5. 更新数据库并清理缓存

运行以下命令应用数据库更新：

drush updb

然后清理缓存：

drush cr

如果出现错误 “Missing $settings['hash_salt'] in settings.php”，请检查是否遗漏复制旧网站 settings.php 中的相关值。

6. 更新 Web 服务器配置

更新 Web 服务器的文档根目录为新的路径，例如 /var/www/sites/new_html/web/。如果使用 PHP-FPM，请同步更新相应配置文件并重启服务。

7. 故障排除

7.1 报告页面中的警告或错误

检查网站的报告页面。如果您未先更新旧网站而直接迁移，可能会因核心或模块版本升级而出现警告或错误。请按常规的 Drupal 更新方式修复。

7.2 缺少 Hash Salt

drupal_missing_hash_salt

如果在运行 drush updb 或 drush cr 时出现 “Missing $settings['hash_salt'] in settings.php” 错误，请复制旧网站 settings.php 中的 hash_salt 值，或运行以下命令生成新的：

drush php-eval 'echo \Drupal\Component\Utility\Crypt::randomBytesBase64(55) . "\n"'

将输出的新哈希值复制到新的 settings.php 文件中即可。

额外区块类型 (EBT) - 全新的布局构建器体验❗

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验