⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

DDEV 开发专家指南：Docker 本地开发环境配置与 Drupal 项目管理

ddev-expert by madsnorgaard/agent-resources

70 周安装量

36 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/madsnorgaard/agent-resources --skill ddev-expert

开发运维 Drupal Docker

🇨🇳中文介绍

DDEV 开发专家

您是一位 DDEV 专家，DDEV 是一个基于 Docker 的 PHP 项目本地开发环境。

核心概念

DDEV 提供了一个一致的、容器化的本地开发环境，包含：

预配置的 PHP、Web 服务器、数据库容器
使用 mkcert 自动配置 HTTPS
内置 Composer 和 Node.js 支持
简便的多项目管理

注意： Drush 默认不包含在内 - 创建 Drupal 项目后，您必须执行 composer require drush/drush。

基本命令

项目管理

ddev start          # 启动项目容器
ddev stop           # 停止项目容器
ddev restart        # 重启容器
ddev poweroff       # 停止所有 DDEV 项目
ddev delete         # 删除项目（保留文件）

执行命令

ddev drush <cmd>    # 运行 Drush 命令
ddev composer <cmd> # 运行 Composer
ddev php <script>   # 运行 PHP 脚本
ddev exec <cmd>     # 在 web 容器中运行任何命令
ddev ssh            # SSH 进入 web 容器

数据库

ddev mysql          # MySQL 命令行界面
ddev export-db      # 导出数据库
ddev import-db      # 导入数据库 (--file=dump.sql)
ddev snapshot       # 创建数据库快照
ddev restore        # 从快照恢复

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

常见自定义配置

自定义服务 (.ddev/docker-compose.*.yaml):

version: '3.6'
services:
  redis:
    image: redis:7
    container_name: ddev-${DDEV_SITENAME}-redis
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
    expose:
      - "6379"

PHP 覆盖配置 (.ddev/php/my-settings.ini):

memory_limit = 512M
upload_max_filesize = 64M
post_max_size = 64M

Nginx 配置 (.ddev/nginx_full/nginx-site.conf): 用于特殊路由需求的自定义 nginx 配置。

新建 Drupal 11 项目

mkdir my-drupal && cd my-drupal
ddev config --project-type=drupal --docroot=web --php-version=8.3
ddev start
ddev composer create-project drupal/recommended-project:^11
ddev composer require drush/drush
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch

ddev composer create-project 需要一个干净的目录 - 先将任何现有文件（如 .claude/）移出，然后在创建项目后再移回
Drupal 11 的 recommended-project 不包含 Drush - 始终需要单独安装
使用 --project-type=drupal（自动检测版本）或明确指定 drupal11

新建 Drupal 10 项目

mkdir my-drupal && cd my-drupal
ddev config --project-type=drupal --docroot=web --php-version=8.2
ddev start
ddev composer create-project drupal/recommended-project:^10
ddev composer require drush/drush
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch

现有 Drupal 项目

cd existing-project
ddev config --project-type=drupal --docroot=web
ddev start
ddev composer install
ddev import-db --file=database.sql.gz
ddev drush cr

ddev composer create-project 失败，提示 "not allowed to be present":

# 当存在额外目录时会发生此问题（如 .claude/, .git/ 等）
# 解决方案：暂时移出它们
mv .claude /tmp/claude-backup
mv .git /tmp/git-backup
ddev composer create-project drupal/recommended-project:^11
mv /tmp/claude-backup .claude
mv /tmp/git-backup .git

ddev poweroff
# 检查是什么占用了 80/443 端口
sudo lsof -i :80

ddev restart
ddev debug refresh    # 重建容器
ddev delete && ddev start  # 终极选项

数据库连接问题：

主机：db（容器内）或 127.0.0.1:PORT（容器外）
使用 ddev describe 检查端口

ddev exec chown -R $(id -u):$(id -g) .

有用的调试命令

ddev debug capabilities  # 显示 DDEV 功能
ddev debug router       # 显示路由器状态
ddev logs -f            # 跟踪日志
ddev exec env           # 显示环境变量

在 .ddev/providers/ 中配置提供者：

# .ddev/providers/platform.yaml
environment_variables:
  project: my-project
  environment: main

db_pull_command:
  command: platform db:dump -e ${environment}

然后执行：ddev pull platform

ddev xdebug on           # 启用步进调试
ddev xdebug off          # 禁用（性能更快）
ddev xdebug status       # 检查当前状态

VS Code （使用 PHP Debug 扩展）：

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

设置 → PHP → 服务器
添加服务器：名称与 DDEV 项目名称匹配
主机：<project>.ddev.site，端口：443，HTTPS
路径映射：项目根目录 → /var/www/html

# .ddev/php/xdebug.ini
[xdebug]
xdebug.mode=debug,develop,coverage

模式：debug（步进调试）、develop（增强错误）、coverage（代码覆盖率）、profile（性能分析）

# .ddev/docker-compose.redis.yaml
services:
  redis:
    image: redis:7-alpine
    container_name: ddev-${DDEV_SITENAME}-redis
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    expose:
      - "6379"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Drupal settings.php：

$settings['redis.connection']['host'] = 'redis';
$settings['redis.connection']['port'] = 6379;
$settings['cache']['default'] = 'cache.backend.redis';

# .ddev/docker-compose.solr.yaml
services:
  solr:
    image: solr:9
    container_name: ddev-${DDEV_SITENAME}-solr
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    expose:
      - "8983"
    volumes:
      - solr-data:/var/solr
    command: solr-precreate drupal

volumes:
  solr-data:

访问 Solr：ddev describe 显示 URL，通常是 https://<project>.ddev.site:8983

# .ddev/docker-compose.elasticsearch.yaml
services:
  elasticsearch:
    image: elasticsearch:8.11.0
    container_name: ddev-${DDEV_SITENAME}-elasticsearch
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    expose:
      - "9200"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data

volumes:
  elasticsearch-data:

Mailpit（电子邮件测试）

DDEV 默认包含 Mailpit：

ddev launch -m           # 打开 Mailpit 界面

所有外发邮件都会被捕获到 https://<project>.ddev.site:8026

Mutagen（macOS/Windows）

Mutagen 提供快速文件同步以获得更好的性能：

# 全局启用
ddev config global --mutagen-enabled

# 或在 .ddev/config.yaml 中按项目启用
mutagen_enabled: true

何时使用 Mutagen：

具有大型代码库的 macOS（vendor, node_modules）
使用 WSL2 的 Windows
文件 I/O 较慢的项目

Mutagen 命令：

ddev mutagen status      # 检查同步状态
ddev mutagen sync        # 强制同步
ddev mutagen reset       # 如有问题则重置

NFS（macOS 替代方案）

对于不使用 Mutagen 的 macOS：

ddev config global --nfs-mount-enabled

从同步中排除不必要的文件：

.ddev/config.yaml

  - sites/default/files

2. 对临时文件使用 tmpfs：

    # .ddev/docker-compose.performance.yaml
services:
  web:
    tmpfs:
      - /tmp

3. 为大型操作增加 PHP 内存：

    # .ddev/php/performance.ini
memory_limit = 1024M

自定义 DDEV 命令

在 .ddev/commands/ 中创建项目特定命令：

# .ddev/commands/web/refresh
#!/bin/bash

## 描述：完整站点刷新（数据库 + 配置 + 缓存）
## 用法：refresh
## 示例：ddev refresh

set -e

echo "正在导入数据库..."
drush sql:drop -y
drush sql:cli < /var/www/html/reference.sql

echo "正在导入配置..."
drush config:import -y

echo "正在运行更新..."
drush updatedb -y

echo "正在清除缓存..."
drush cache:rebuild

echo "完成！"

设置为可执行：chmod +x .ddev/commands/web/refresh

然后运行：ddev refresh

.ddev/commands/web/ - 在 web 容器中运行
.ddev/commands/host/ - 在宿主机上运行
.ddev/commands/db/ - 在数据库容器中运行

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup DDEV
        uses: ddev/github-action-setup-ddev@v1

      - name: Start DDEV
        run: ddev start

      - name: Install dependencies
        run: ddev composer install

      - name: Run tests
        run: ddev exec ./vendor/bin/phpunit

# .gitlab-ci.yml
test:
  image: ddev/ddev-gitpod-base:latest
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
  script:
    - ddev start
    - ddev composer install
    - ddev exec ./vendor/bin/phpunit

提交 .ddev 文件夹（.ddev/db_snapshots 除外，.ddev/.gitignore 已处理此问题）
使用 .ddev/config.local.yaml 进行个人覆盖配置（已 gitignore）
在项目 README 中记录自定义服务
在执行有风险的数据库操作前使用快照
保持 DDEV 更新：ddev self-upgrade
在 macOS/Windows 上使用 Mutagen 以获得更好的性能
为重复性任务创建自定义命令
在 CI 中测试 DDEV 配置 以尽早发现问题

🇺🇸English

DDEV Development Expert

You are an expert in DDEV, the Docker-based local development environment for PHP projects.

Core Concepts

DDEV provides a consistent, containerized local development environment with:

Pre-configured PHP, web server, database containers
Automatic HTTPS with mkcert
Built-in Composer and Node.js support
Easy multi-project management

Note: Drush is NOT included by default - you must composer require drush/drush after creating a Drupal project.

Essential Commands

Project Management

ddev start          # Start project containers
ddev stop           # Stop project containers
ddev restart        # Restart containers
ddev poweroff       # Stop all DDEV projects
ddev delete         # Remove project (keeps files)

Executing Commands

ddev drush <cmd>    # Run Drush commands
ddev composer <cmd> # Run Composer
ddev php <script>   # Run PHP scripts
ddev exec <cmd>     # Run any command in web container
ddev ssh            # SSH into web container

Database

ddev mysql          # MySQL CLI
ddev export-db      # Export database
ddev import-db      # Import database (--file=dump.sql)
ddev snapshot       # Create database snapshot
ddev restore        # Restore from snapshot

Utilities

ddev describe       # Show project info and URLs
ddev logs           # View container logs
ddev launch         # Open site in browser
ddev share          # Create public URL (ngrok)

Configuration

.ddev/config.yaml

name: my-project
type: drupal           # Auto-detects Drupal version, or use drupal11/drupal10
docroot: web
php_version: "8.3"     # Use 8.3 for Drupal 11, 8.2 for Drupal 10
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.11"

# Additional hostnames
additional_hostnames:
  - api.my-project.ddev.site

# Extra PHP packages
webimage_extra_packages: [php8.3-imagick]

Common Customizations

Custom services (.ddev/docker-compose.*.yaml):

version: '3.6'
services:
  redis:
    image: redis:7
    container_name: ddev-${DDEV_SITENAME}-redis
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
    expose:
      - "6379"

PHP overrides (.ddev/php/my-settings.ini):

memory_limit = 512M
upload_max_filesize = 64M
post_max_size = 64M

Nginx config (.ddev/nginx_full/nginx-site.conf): Custom nginx configuration for special routing needs.

Drupal-Specific Setup

New Drupal 11 Project

mkdir my-drupal && cd my-drupal
ddev config --project-type=drupal --docroot=web --php-version=8.3
ddev start
ddev composer create-project drupal/recommended-project:^11
ddev composer require drush/drush
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch

Important notes:

ddev composer create-project requires a clean directory - move any existing files (like .claude/) out first, then move them back after
Drush is NOT included in Drupal 11's recommended-project - always install it separately
Use --project-type=drupal (auto-detects version) or explicitly drupal11

New Drupal 10 Project

mkdir my-drupal && cd my-drupal
ddev config --project-type=drupal --docroot=web --php-version=8.2
ddev start
ddev composer create-project drupal/recommended-project:^10
ddev composer require drush/drush
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch

Existing Drupal Project

cd existing-project
ddev config --project-type=drupal --docroot=web
ddev start
ddev composer install
ddev import-db --file=database.sql.gz
ddev drush cr

Troubleshooting

Common Issues

ddev composer create-project fails with "not allowed to be present":

# This happens when extra directories exist (like .claude/, .git/, etc.)
# Solution: Move them out temporarily
mv .claude /tmp/claude-backup
mv .git /tmp/git-backup
ddev composer create-project drupal/recommended-project:^11
mv /tmp/claude-backup .claude
mv /tmp/git-backup .git

Port conflicts:

ddev poweroff
# Check what's using ports 80/443
sudo lsof -i :80

Container issues:

ddev restart
ddev debug refresh    # Rebuild containers
ddev delete && ddev start  # Nuclear option

Database connection issues:

Host: db (inside container) or 127.0.0.1:PORT (outside)
Check port with ddev describe

Permission issues:

ddev exec chown -R $(id -u):$(id -g) .

Useful Debug Commands

ddev debug capabilities  # Show DDEV capabilities
ddev debug router       # Show router status
ddev logs -f            # Follow logs
ddev exec env           # Show environment variables

Multi-Environment Workflows

Using ddev pull

Configure providers in .ddev/providers/:

# .ddev/providers/platform.yaml
environment_variables:
  project: my-project
  environment: main

db_pull_command:
  command: platform db:dump -e ${environment}

Then: ddev pull platform

Xdebug Configuration

Enable Xdebug

ddev xdebug on           # Enable step debugging
ddev xdebug off          # Disable (faster performance)
ddev xdebug status       # Check current state

IDE Configuration

VS Code (with PHP Debug extension):

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

PHPStorm :

Settings → PHP → Servers
Add server: name matches DDEV project name
Host: <project>.ddev.site, Port: 443, HTTPS
Path mappings: project root → /var/www/html

Xdebug Modes

# .ddev/php/xdebug.ini
[xdebug]
xdebug.mode=debug,develop,coverage

Modes: debug (step debugging), develop (enhanced errors), coverage (code coverage), profile (profiling)

Custom Services

Redis

# .ddev/docker-compose.redis.yaml
services:
  redis:
    image: redis:7-alpine
    container_name: ddev-${DDEV_SITENAME}-redis
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    expose:
      - "6379"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Drupal settings.php:

$settings['redis.connection']['host'] = 'redis';
$settings['redis.connection']['port'] = 6379;
$settings['cache']['default'] = 'cache.backend.redis';

Solr

# .ddev/docker-compose.solr.yaml
services:
  solr:
    image: solr:9
    container_name: ddev-${DDEV_SITENAME}-solr
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    expose:
      - "8983"
    volumes:
      - solr-data:/var/solr
    command: solr-precreate drupal

volumes:
  solr-data:

Access Solr: ddev describe shows URL, typically https://<project>.ddev.site:8983

Elasticsearch

# .ddev/docker-compose.elasticsearch.yaml
services:
  elasticsearch:
    image: elasticsearch:8.11.0
    container_name: ddev-${DDEV_SITENAME}-elasticsearch
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: $DDEV_APPROOT
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    expose:
      - "9200"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data

volumes:
  elasticsearch-data:

Mailpit (Email Testing)

DDEV includes Mailpit by default:

ddev launch -m           # Open Mailpit UI

All outgoing mail is captured at https://<project>.ddev.site:8026

Performance Tuning

Mutagen (macOS/Windows)

Mutagen provides fast file synchronization for better performance:

# Enable globally
ddev config global --mutagen-enabled

# Or per-project in .ddev/config.yaml
mutagen_enabled: true

When to use Mutagen:

macOS with large codebases (vendor, node_modules)
Windows with WSL2
Projects with slow file I/O

Mutagen commands:

ddev mutagen status      # Check sync status
ddev mutagen sync        # Force sync
ddev mutagen reset       # Reset if issues

NFS (macOS alternative)

For macOS without Mutagen:

ddev config global --nfs-mount-enabled

Performance Tips

Exclude unnecessary files from sync:

.ddev/config.yaml

upload_dirs:

  - sites/default/files

2. Use tmpfs for temp files :

    # .ddev/docker-compose.performance.yaml
services:
  web:
    tmpfs:
      - /tmp

3. Increase PHP memory for large operations :

    # .ddev/php/performance.ini
memory_limit = 1024M

Custom DDEV Commands

Create project-specific commands in .ddev/commands/:

# .ddev/commands/web/refresh
#!/bin/bash

## Description: Full site refresh (db + config + cache)
## Usage: refresh
## Example: ddev refresh

set -e

echo "Importing database..."
drush sql:drop -y
drush sql:cli < /var/www/html/reference.sql

echo "Importing config..."
drush config:import -y

echo "Running updates..."
drush updatedb -y

echo "Clearing cache..."
drush cache:rebuild

echo "Done!"

Make executable: chmod +x .ddev/commands/web/refresh

Then run: ddev refresh

Command Locations

.ddev/commands/web/ - Run in web container
.ddev/commands/host/ - Run on host machine
.ddev/commands/db/ - Run in database container

CI/CD Integration

GitHub Actions

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup DDEV
        uses: ddev/github-action-setup-ddev@v1

      - name: Start DDEV
        run: ddev start

      - name: Install dependencies
        run: ddev composer install

      - name: Run tests
        run: ddev exec ./vendor/bin/phpunit

GitLab CI

# .gitlab-ci.yml
test:
  image: ddev/ddev-gitpod-base:latest
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://docker:2375
  script:
    - ddev start
    - ddev composer install
    - ddev exec ./vendor/bin/phpunit

Best Practices

Commit .ddev folder (except .ddev/db_snapshots, .ddev/.gitignore handles this)
Use .ddev/config.local.yaml for personal overrides (gitignored)
Document custom services in project README
Use snapshots before risky database operations
Keep DDEV updated : ddev self-upgrade
Use Mutagen on macOS/Windows for better performance
Create custom commands for repetitive tasks
Test DDEV config in CI to catch issues early

Weekly Installs

Repository

madsnorgaard/ag…esources

GitHub Stars

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode66

gemini-cli59

codex59

cursor57

github-copilot57

amp54

Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU

111,700 周安装

DDEV 开发专家指南：Docker 本地开发环境配置与 Drupal 项目管理

🇨🇳中文介绍

DDEV 开发专家

核心概念

基本命令

项目管理

执行命令

数据库

相关 Skills

实用工具

配置

.ddev/config.yaml

常见自定义配置

Drupal 特定设置

新建 Drupal 11 项目

新建 Drupal 10 项目

现有 Drupal 项目

故障排除

常见问题

有用的调试命令

多环境工作流

使用 ddev pull

Xdebug 配置

启用 Xdebug

IDE 配置

Xdebug 模式

自定义服务

Redis

Solr

Elasticsearch

Mailpit（电子邮件测试）

性能调优

Mutagen（macOS/Windows）

NFS（macOS 替代方案）

性能提示

.ddev/config.yaml

自定义 DDEV 命令

命令位置

CI/CD 集成

GitHub Actions

GitLab CI

最佳实践

🇺🇸English

DDEV Development Expert

Core Concepts

Essential Commands

Project Management

Executing Commands

Database

Utilities

Configuration

.ddev/config.yaml

Common Customizations

Drupal-Specific Setup

New Drupal 11 Project

New Drupal 10 Project

Existing Drupal Project

Troubleshooting

Common Issues

Useful Debug Commands

Multi-Environment Workflows

Using ddev pull

Xdebug Configuration

Enable Xdebug

IDE Configuration

Xdebug Modes

Custom Services

Redis

Solr

Elasticsearch

Mailpit (Email Testing)

Performance Tuning

Mutagen (macOS/Windows)

NFS (macOS alternative)

Performance Tips

.ddev/config.yaml

Custom DDEV Commands

Command Locations

CI/CD Integration

GitHub Actions