composer如何安装Drupal框架_使用composer安装Drupal详细步骤【教程】

composer create-project drupal/recommended-project 是唯一推荐的安装方式，因其严格遵循 web/ 为文档根的目录结构、预置 installer-paths 和 scaffold 钩子，避免核心覆盖、自动加载失效及升级崩溃等问题。

为什么不能从 drupal.org 下载 zip 包再装 Composer？

Drupal 官方 tar 包（如 drupal-10.2.0.tar.gz）是面向传统 FTP 部署设计的：它把 core/、modules/、themes/ 全平铺在根目录，而 Composer 管理的项目必须严格遵循 web/ 为文档根的结构。一旦你在这个结构上强行运行 composer require，Composer 插件（如 drupal-composer-scaffold）会尝试移动文件，但往往失败或残留冲突路径。

• 现象：执行 composer require drupal/pathauto 后模块没进 web/modules/contrib/，反而出现在根目录 modules/ 下
• 后果：drush 找不到模块，Web 服务器可能暴露 composer.json 或 vendor/
• 根本原因：缺少 installer-paths 配置和 drupal/core-composer-scaffold 的钩子支持

正确安装：一条命令 + 两个确认点

运行以下命令即可生成开箱即用的 Drupal 项目：

composer create-project drupal/recommended-project my-site

执行后需立刻确认两件事：

Favird No-Code Tools

无代码工具的聚合器

下载

• my-site/web/ 存在且包含 index.php、.htaccess —— 这是 Web 服务器 DocumentRoot 必须指向的位置
• my-site/composer.json 中有 "drupal/core-recommended": "^10.2"（以 Drupal 10.2 为例），而非 "drupal/core": "*" —— 锁定范围可防止意外升到不兼容版本
• 检查 my-site/web/sites/default/settings.php 是否已生成（若无，需复制 default.settings.php 并赋权）

安装后第一件事：别急着启用模块，先跑通环境

很多新手在 composer create-project 后直接 drush en pathauto，结果报错 “Class not found”。这不是模块问题，而是 autoloader 没生效或权限未设好。

• 确保 PHP CLI 使用的版本 ≥ 8.1（Drupal 10 要求），运行 php -v 验证
• 进入 my-site/ 目录，运行 composer install --no-dev --optimize-autoloader（生产环境部署必加参数）
• 设置 web/sites/default/files/ 和 web/sites/default/settings.php 为可写（Linux/macOS：chmod 755 files; chmod 644 settings.php）
• 用 drush site:install standard --db-url=sqlite://sites/default/files/.ht.sqlite 快速初始化（SQLite 无需配置数据库）

常见卡点：国内网络慢、权限报错、PHP 版本错位

这三类问题占安装失败的 90% 以上，且都有确定解法：

• 连接 Packagist 太慢或超时：运行 composer config -g repo.packagist composer https://packagist.phpcomposer.com（阿里云镜像），再重试 create-project
• 提示 “Permission denied” 写 vendor/ 或 web/sites/default/files：不要用 sudo composer，改用 chown -R $USER:$USER my-site/ 修正归属
• PHP 版本不匹配（如报 “Attribute is not allowed here”）：确认系统默认 PHP 是 8.1+，不是系统自带的 7.4；macOS 用户可用 brew install php@8.1 && brew link php@8.1 --force