最稳安装路径是用 composer create-project，因 Drupal 核心深度依赖 Composer 管理自动加载与模块；手动解压、clone 或 require drupal/core 均会破坏目录结构与 autoload 映射，导致站点无法启动或模块失效。
直接用 composer create-project 安装 Drupal 8/9/10 是最稳的路径
官方不再推荐下载 tar.gz 包手动解压，因为 Drupal 核心已深度依赖 Composer 管理模块、库和自动加载。跳过 composer create-project 直接 clone 或复制文件，会导致 vendor/autoload.php 缺失、drush 无法识别命令、甚至站点完全无法启动。
实操建议：
- 确保系统已安装 PHP ≥ 8.1（Drupal 10）、Composer 2.5+，且
openssl和mbstring扩展已启用 - 运行命令时始终在**空目录**中执行，避免与已有
composer.json冲突 - 指定版本号比用
dev-main更可控，例如安装 Drupal 10.2：composer create-project drupal/recommended-project:10.2.0 my-drupal-site
- 若提示
zlib_decode(): data error，通常是 Composer 缓存损坏，先运行composer clear-cache
为什么不能用 composer require drupal/core 升级或“补装”核心？
drupal/core 是被锁定的“不可直接 require”的包。它只作为 drupal/recommended-project 的子依赖存在，且受 composer/installers 和 drupal-core-require-dev 等插件协同约束。手动 require 会破坏 Drupal 的目录结构约定（如 web/ 入口隔离）和自动加载映射。
常见错误现象：
-
drush status报错Could not find a Drupal settings.php file—— 因为web/sites/default/settings.php未生成，且autoload未按 Drupal 规范注册 - 后台启用模块时报
Class 'Drupal\xxx\XxxServiceProvider' not found—— 模块未被drupal/core-composer-scaffold正确注入到web/modules/ -
composer update后web/index.php404 ——drupal/core被降级，导致web/目录内容被清空
添加模块时必须用 composer require --no-update + composer update 分两步
Drupal 模块（如 drupal pathauto）不是普通 PHP 包，其安装过程需触发 drupal-scaffold 插件将文件复制到 web/modules/contrib/，并更新 autoload-dev 映射。一步到位的 composer require drupal/pathauto 在某些网络或权限环境下会卡在 scaffold 阶段，导致模块文件存在但未生效。
稳妥做法：
- 先执行
composer require drupal/pathauto --no-update，仅修改composer.json - 再运行
composer update drupal/pathauto --with-all-dependencies，强制触发 scaffold 和 autoload 重写 - 检查
web/modules/contrib/pathauto/是否真实存在，且composer show drupal/pathauto输出版本与composer.json一致 - 若模块含 JS/CSS 资源，还需确认
drupal/core-dev是否启用 —— 否则drupal:fix-permissions脚本不会运行，导致web/sites/default/files权限异常
vendor 目录挪动或 symlink 到 web/ 外部会破坏 Drupal 运行时加载
有人为节省空间或适配旧部署习惯，把 vendor/ 移到 ../vendor 并加软链，或改 autoload.php 路径。这在 CLI 下可能暂时正常，但在 Web Server（Apache/Nginx）下极易失败，因为 Drupal 的 web/index.php 依赖固定相对路径加载 ../vendor/autoload.php，且 drupal/core-composer-scaffold 的所有钩子都硬编码了该结构。
关键细节：
-
web/autoload.php是 scaffold 自动生成的代理文件，内容固定为require_once __DIR__ . '/../vendor/autoload.php';，不可手动修改 - Web Server 的工作目录是
web/，PHP 的getcwd()返回的是该路径，因此../vendor必须真实存在且可读 - 若用 Docker，务必挂载整个项目根目录（含
composer.json和vendor/），而非只挂载web/
复杂点在于：很多 CI/CD 流程试图“优化” vendor 位置，结果在预发布环境暴露问题。只要保持 composer.json → vendor/ → web/ 三层垂直结构不动，绝大多数依赖问题就消除了。
