composer create-project drupal/recommended-project 是唯一推荐的安装方式，因其严格遵循 web/ 为文档根的目录结构、预置 installer-paths 和 scaffold 钩子，避免核心覆盖、自动加载失效及升级崩溃等问题。
composer create-project drupal/recommended-project 是当前唯一推荐的安装方式。手动下载 tar 包、解压后补 Composer，或直接在空目录里 composer init 再加 drupal/core，都会导致目录结构错乱、核心文件被覆盖、自动加载失效——这些不是“能用就行”的小问题，而是后续升级和部署必然崩溃的根源。
为什么不能从 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
执行后需立刻确认两件事：
-
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
drupal/recommended-project 这个起点。它不是可选项，是 Drupal Composer 工作流的强制入口。 
