drupal-tooling

Drupal 开发工具

概述

借助针对 DDEV Docker 本地开发环境和 Drupal 8、9、10、11+ 的 Drush 命令行操作的全面指南，启用专家级 Drupal 开发工具功能。

何时使用此技能

在以下场景中调用此技能：

• DDEV 操作：启动、管理或配置本地开发环境
• Drush 命令：站点管理、配置和缓存操作
• 数据库管理：导入/导出、快照和迁移
• 部署工作流：配置同步和数据库更新
• 开发环境搭建：项目初始化和环境配置
• 故障排查：调试环境或命令行问题

核心功能

1. DDEV 本地开发

高效管理基于 Docker 的本地 Drupal 环境：

项目初始化：

# Initialize new Drupal project
ddev config --project-type=drupal10 --docroot=web --create-docroot

# Start containers
ddev start

# Install Drupal via Composer
ddev composer create drupal/recommended-project

# Install Drupal site
ddev drush site:install standard --account-name=admin --account-pass=admin

日常操作：

# Start/stop project
ddev start
ddev stop
ddev restart

# SSH into container
ddev ssh

# Launch site in browser
ddev launch

# View logs
ddev logs
ddev logs -f  # Follow logs

数据库操作：

# Import database
ddev import-db --src=database.sql.gz

# Export database
ddev export-db --file=backup.sql.gz --gzip

# Create snapshot
ddev snapshot

# Restore snapshot
ddev snapshot restore

# Access MySQL CLI
ddev mysql

参考文档：

• references/ddev.md - 完整的 DDEV 参考文档

2. Drush 命令行管理

高效执行站点管理任务：

缓存管理：

# Rebuild cache (most common)
ddev drush cr

# Clear specific cache
ddev drush cache:clear css-js
ddev drush cache:clear render

配置管理：

# Export configuration
ddev drush config:export
ddev drush cex

# Import configuration
ddev drush config:import
ddev drush cim

# View configuration
ddev drush config:get system.site
ddev drush cget system.site

# Set configuration
ddev drush config:set system.site name "My Site"
ddev drush cset system.site name "My Site"

模块管理：

# Enable module
ddev drush pm:enable mymodule -y
ddev drush en mymodule -y

# Uninstall module
ddev drush pm:uninstall mymodule -y
ddev drush pmu mymodule -y

# List modules
ddev drush pm:list
ddev drush pml

# Download module
ddev drush pm:download webform

数据库更新：

# Run pending database updates
ddev drush updatedb -y
ddev drush updb -y

用户管理：

# One-time login URL
ddev drush user:login
ddev drush uli

# Login as specific user
ddev drush uli admin

# Create user
ddev drush user:create newuser --mail="[email protected]" --password="pass"

# Change password
ddev drush user:password admin "newpassword"

参考文档：

• references/drush.md - 完整的 Drush 参考文档

3. 开发工作流

常见的开发和部署工作流：

标准部署：

# Run database updates
ddev drush updb -y

# Import configuration
ddev drush cim -y

# Clear cache
ddev drush cr

# One-liner version
ddev drush updb -y && ddev drush cim -y && ddev drush cr

全新站点设置：

# Clone repository
git clone <repo> myproject
cd myproject

# Start DDEV
ddev start

# Install dependencies
ddev composer install

# Import database and files
ddev import-db --src=database.sql.gz
ddev import-files --src=files.tar.gz

# Clear cache
ddev drush cr

# Launch site
ddev launch

主题/模块开发：

# Start work
ddev start

# Clear cache frequently
ddev drush cr

# Watch for changes (if using build tools)
ddev exec npm run watch

# View logs
ddev drush watchdog:tail

4. 代码生成

使用 Drush 生成器搭建代码框架：

# Generate module
ddev drush generate module

# Generate controller
ddev drush generate controller

# Generate form
ddev drush generate form

# Generate plugin block
ddev drush generate plugin:block

# Generate service
ddev drush generate service

# Generate theme
ddev drush generate theme

# Generate hook
ddev drush generate hook

# List all generators
ddev drush generate --help

5. 调试与故障排查

调试并监控 Drupal 站点：

启用 Xdebug：

# Enable Xdebug
ddev xdebug on

# Disable Xdebug (improves performance)
ddev xdebug off

# Check status
ddev xdebug status

查看日志：

# Recent watchdog messages
ddev drush watchdog:show

# Follow watchdog logs
ddev drush watchdog:tail

# Container logs
ddev logs -s web
ddev logs -s db

项目信息：

# Show project details
ddev describe

# Drupal status
ddev drush status
ddev drush st

# List all DDEV projects
ddev list

最佳实践

DDEV 最佳实践

1. 通过 DDEV 运行工具：始终使用 ddev drush、ddev composer、ddev npm
2. 快照：在执行高风险操作前创建快照
3. 性能：启用 Mutagen（Mac）或 NFS，以提升文件同步速度
4. Xdebug：仅在调试时启用
5. 版本控制：提交 .ddev/config.yaml 以共享配置
6. 正常关闭：关闭系统前使用 ddev stop

Drush 最佳实践

1. 别名：使用短别名（cr、cex、cim、uli）
2. 自动化：添加 -y 标志以跳过确认
3. 自定义命令：为重复性任务创建自定义命令
4. 站点别名：配置别名以管理多个环境
5. 串联命令：使用 && 按顺序执行操作
6. 错误处理：在脚本中检查退出代码

部署最佳实践

1. 顺序：先运行更新（updb），再导入配置（cim）
2. 测试：先在预发布环境中测试部署工作流
3. 备份：进行重大更改前务必备份
4. 回滚计划：准备好还原更改的方法
5. 监控：部署后检查日志

常见操作

为现有项目初始化 DDEV

cd existing-project

# Configure DDEV
ddev config

# Start containers
ddev start

# Install dependencies
ddev composer install

# Import database (if available)
ddev import-db --src=backup.sql.gz

# Clear cache
ddev drush cr

从远程环境拉取数据

# Configure Drush alias for remote site
# Then pull database and files
ddev pull @production

# Or pull separately
ddev drush sql:sync @production @self
ddev rsync @production:%files @self:%files

更新 Drupal Core

# Backup first
ddev snapshot

# Update with Composer
ddev composer update drupal/core "drupal/core-*" --with-all-dependencies

# Run database updates
ddev drush updb -y

# Clear cache
ddev drush cr

启用开发设置

# Copy development settings
cp sites/example.settings.local.php sites/default/settings.local.php

# Disable CSS/JS aggregation via Drush
ddev drush config:set system.performance css.preprocess 0 -y
ddev drush config:set system.performance js.preprocess 0 -y

# Enable Twig debugging
# Edit sites/default/services.yml:
# twig.config:
#   debug: true
#   auto_reload: true
#   cache: false

# Clear cache
ddev drush cr

故障排查

DDEV 问题

容器无法启动：

# Check Docker is running
docker ps

# Restart DDEV
ddev restart

# Power off and restart
ddev poweroff
ddev start

# Clean restart
ddev restart --clean

端口冲突：

# Check what's using ports
ddev describe

# Change ports in .ddev/config.yaml:
# router_http_port: "8080"
# router_https_port: "8443"

# Restart
ddev restart

权限问题：

# Fix file permissions
ddev exec chmod -R 755 web/sites/default/files
ddev exec chown -R www-data:www-data web/sites/default/files

Drush 问题

找不到 Drush：

# Always run through DDEV
ddev drush status

# Not just: drush status

配置同步失败：

# Check for overridden configuration
ddev drush config:status

# Force import
ddev drush cim -y --partial

# Check specific config
ddev drush config:get system.site

数据库更新失败：

# Run with verbose output
ddev drush updb -v

# Check specific module updates
ddev drush updatedb:status

# Check logs
ddev drush watchdog:show

性能优化

DDEV 性能（Mac）

启用 Mutagen：

# In .ddev/config.yaml
ddev config --mutagen-enabled

# Restart
ddev restart

启用 NFS：

# In .ddev/config.yaml
ddev config --nfs-mount-enabled

# Restart
ddev restart

Drush 性能

不调试时禁用 Xdebug：

ddev xdebug off

使用具体命令，而非别名：

# Faster (loads less)
ddev drush cache:rebuild

# vs
ddev drush cr

资源

参考文档

• references/ddev.md - 完整的 DDEV 参考文档

  • 项目初始化和配置
  • 数据库和文件操作
  • 附加组件和服务（Redis、Elasticsearch 等）
  • 性能优化
  • 故障排除

• references/drush.md - 完整的 Drush 参考文档

  • 缓存管理命令
  • 配置管理
  • 模块和主题操作
  • 数据库操作
  • 用户管理
  • 自定义命令开发

搜索参考文档

# Find DDEV command
grep -r "ddev snapshot" references/

# Find Drush command
grep -r "config:import" references/

# Find deployment info
grep -r "deployment" references/

常见用例

本地开发环境设置

1. 克隆项目：git clone <repo>
2. 配置 DDEV：ddev config
3. 启动：ddev start
4. 安装依赖：ddev composer install
5. 导入数据库：ddev import-db --src=db.sql.gz
6. 清除缓存：ddev drush cr
7. 启动：ddev launch

部署配置更改

1. 导出配置：ddev drush cex -y
2. 提交到 git：git add config/ && git commit
3. 推送：git push
4. 在服务端执行：drush cim -y && drush cr

排查性能问题

1. 启用 Xdebug：ddev xdebug on
2. 在 IDE 中设置断点
3. 触发请求：ddev launch
4. 单步调试代码
5. 禁用 Xdebug：ddev xdebug off

版本兼容性

DDEV 版本

• 推荐使用 DDEV v1.21+
• 支持所有 Drupal 版本（8-11+）
• 使用以下命令更新：brew upgrade ddev（Mac）或对应平台的等效命令

Drush 版本

• Drupal 8.4+ 使用 Drush 10+
• Drupal 9.0+ 使用 Drush 11+
• Drupal 10.0+ 使用 Drush 12+
• 通过 Composer 安装（项目专用）

另请参阅

• drupal-frontend - 主题开发和 Twig 模板
• drupal-backend - 模块开发和 API
• DDEV 文档 - DDEV 官方文档
• Drush 文档 - Drush 官方文档
• DDEV Discord - 社区支持