TYPO3 DDEV Local Development

TYPO3 基于DDEV的本地开发

Compatibility: TYPO3 v13.x and v14.x (v14 preferred) All configurations in this skill support both TYPO3 v13 and v14.

TYPO3 API First: Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in your target TYPO3 version (v13 or v14) by checking the official TYPO3 documentation.

兼容性： TYPO3 v13.x 和 v14.x（推荐使用v14）本技能中的所有配置均支持TYPO3 v13和v14版本。

TYPO3 API优先原则： 在创建自定义实现之前，始终优先使用TYPO3的内置API、核心功能和既定规范。不要重复造轮子。在使用API和方法前，务必通过官方TYPO3文档确认它们在目标版本（v13或v14）中存在且未被弃用。

Container Priority

容器使用优先级

Always check for existing containers first:

Check
```
.ddev/
```
exists → use
```
ddev exec
```
Check
```
docker-compose.yml
```
exists → use
```
docker compose exec
```
Only use system tools if no container environment

Critical: Use the project's configured PHP version, not system PHP.

始终优先检查现有容器：

检查是否存在
```
.ddev/
```
目录 → 使用
```
ddev exec
```
检查是否存在
```
docker-compose.yml
```
文件 → 使用
```
docker compose exec
```
仅在没有容器环境时使用系统工具

重要提示： 使用项目配置的PHP版本，而非系统PHP。

1. Project Initialization

1. 项目初始化

New TYPO3 Project (v14 - Preferred)

新建TYPO3项目（v14 - 推荐）

bash

undefined

bash

undefined

Create project directory

创建项目目录

mkdir my-typo3-project && cd my-typo3-project

Initialize DDEV with TYPO3 preset

使用TYPO3预设初始化DDEV

ddev config --project-type=typo3 --docroot=public --php-version=8.3

Start the environment

启动开发环境

ddev start

Install TYPO3 v14 (preferred)

安装TYPO3 v14（推荐版本）

ddev composer create "typo3/cms-base-distribution:^14"

Run TYPO3 setup

运行TYPO3安装向导

ddev typo3 setup

undefined

ddev typo3 setup

undefined

New TYPO3 Project (v13 LTS)

新建TYPO3项目（v13 LTS）

bash

undefined

bash

undefined

Create project directory

创建项目目录

mkdir my-typo3-project && cd my-typo3-project

Initialize DDEV with TYPO3 preset

使用TYPO3预设初始化DDEV

ddev config --project-type=typo3 --docroot=public --php-version=8.2

Start the environment

启动开发环境

ddev start

Install TYPO3 v13 LTS

安装TYPO3 v13 LTS版本

ddev composer create "typo3/cms-base-distribution:^13"

Run TYPO3 setup

运行TYPO3安装向导

ddev typo3 setup

undefined

ddev typo3 setup

undefined

Existing TYPO3 Project

现有TYPO3项目

bash

undefined

bash

undefined

Clone repository

克隆代码仓库

git clone git@github.com:org/project.git cd project

Configure DDEV (if not already)

配置DDEV（如果尚未配置）

ddev config --project-type=typo3 --docroot=public --php-version=8.3

Start and install dependencies

启动环境并安装依赖

ddev start ddev composer install

Import database (see Database Operations)

导入数据库（详见数据库操作章节）

undefined

undefined

2. Recommended Configuration

2. 推荐配置

.ddev/config.yaml

(v13/v14 Compatible)

.ddev/config.yaml

（兼容v13/v14）

yaml

name: my-typo3-project
type: typo3
docroot: public
php_version: "8.3"    # 8.2 minimum for v13, 8.3 recommended for v14
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.11"    # 10.11+ or 11.x recommended for both v13/v14

yaml

name: my-typo3-project
type: typo3
docroot: public
php_version: "8.3"    # v13最低要求PHP 8.2，v14推荐使用PHP 8.3
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.11"    # v13/v14均推荐使用10.11+或11.x版本

Fixed port for external tools (MySQL MCP, etc.)

为外部工具（如MySQL MCP等）设置固定端口

host_db_port: "33060" host_webserver_port: "8080" host_https_port: "8443"

Enable Mailpit for email testing (replaced Mailhog in newer DDEV)

启用Mailpit进行邮件测试（在新版DDEV中替代了Mailhog）

mailpit_http_port: "8025"

PHP settings

PHP设置

web_environment:

TYPO3_CONTEXT=Development
PHP_IDE_CONFIG=serverName=my-typo3-project.ddev.site

web_environment:

TYPO3_CONTEXT=Development
PHP_IDE_CONFIG=serverName=my-typo3-project.ddev.site

Additional services

额外服务

hooks: post-start: - exec: composer install --no-interaction

undefined

hooks: post-start: - exec: composer install --no-interaction

undefined

.ddev/config.local.yaml

(Personal Overrides)

.ddev/config.local.yaml

（个人自定义配置）

yaml

undefined

yaml

undefined

Personal machine-specific overrides (gitignored)

针对个人机器的自定义配置（需加入.gitignore）

host_db_port: "33061" # If 33060 conflicts

undefined

host_db_port: "33061" # 如果33060端口被占用则修改

undefined

PHP Version Matrix

PHP版本对应表

TYPO3 Version	Minimum PHP	Recommended PHP	MariaDB
v13.4 LTS	8.2	8.3	10.11+
v14.x	8.2	8.3 / 8.4	10.11+

TYPO3版本	最低PHP版本	推荐PHP版本	MariaDB版本
v13.4 LTS	8.2	8.3	10.11+
v14.x	8.2	8.3 / 8.4	10.11+

3. Database Operations

3. 数据库操作

Import Database

导入数据库

bash

undefined

bash

undefined

From SQL file

从SQL文件导入

ddev import-db --file=dump.sql

From gzipped file

从压缩的SQL文件导入

ddev import-db --file=dump.sql.gz

From remote (via SSH)

从远程服务器导入（通过SSH）

ssh user@server "mysqldump -u root dbname | gzip" | gunzip | ddev import-db

undefined

ssh user@server "mysqldump -u root dbname | gzip" | gunzip | ddev import-db

undefined

Export Database

导出数据库

bash

undefined

bash

undefined

Standard export

标准导出（压缩格式）

ddev export-db --file=backup.sql.gz

Without gzip

不压缩导出

ddev export-db --gzip=false --file=backup.sql

undefined

ddev export-db --gzip=false --file=backup.sql

undefined

Database Snapshots

数据库快照

bash

undefined

bash

undefined

Create snapshot before risky operation

在执行高风险操作前创建快照

ddev snapshot --name=before-upgrade

List snapshots

列出所有快照

ddev snapshot --list

Restore snapshot

恢复快照

ddev snapshot restore before-upgrade

Delete snapshot

删除快照

ddev snapshot delete before-upgrade

undefined

ddev snapshot delete before-upgrade

undefined

Direct MySQL Access

直接访问MySQL

bash

undefined

bash

undefined

MySQL CLI

进入MySQL命令行

ddev mysql

Execute query

执行查询语句

ddev mysql -e "SELECT uid, title FROM pages WHERE hidden = 0"

Connect from external tool (e.g., TablePlus, DBeaver)

通过外部工具连接（如TablePlus、DBeaver）

Host: 127.0.0.1

主机：127.0.0.1

Port: 33060 (or your configured host_db_port)

端口：33060（或你配置的host_db_port）

User: db

用户名：db

Password: db

密码：db

Database: db

数据库名：db

undefined

undefined

4. TYPO3 CLI Commands

4. TYPO3 CLI命令

Console Commands

控制台命令

bash

undefined

bash

undefined

List all commands

列出所有可用命令

ddev typo3 list

Clear all caches

清空所有缓存

ddev typo3 cache:flush

Clear specific cache

清空指定类型的缓存

ddev typo3 cache:flush --group=pages

Update database schema

更新数据库表结构

ddev typo3 database:updateschema

Reference index

更新引用索引

ddev typo3 referenceindex:update

Scheduled tasks

执行定时任务

ddev typo3 scheduler:run

Run upgrade wizards (after version update)

运行升级向导（版本更新后）

ddev typo3 upgrade:list ddev typo3 upgrade:run

undefined

ddev typo3 upgrade:list ddev typo3 upgrade:run

undefined

Extension Management

扩展管理

bash

undefined

bash

undefined

Install extension from TER

从TER安装扩展

ddev composer require typo3/cms-seo

Install extension from Packagist

从Packagist安装扩展

ddev composer require vendor/extension-name

Setup extensions (generate PackageStates.php)

初始化扩展（生成PackageStates.php）

ddev typo3 extension:setup

Activate extension

启用扩展

ddev typo3 extension:activate my_extension

Deactivate extension

禁用扩展

ddev typo3 extension:deactivate my_extension

undefined

ddev typo3 extension:deactivate my_extension

undefined

5. Composer Operations

5. Composer操作

bash

undefined

bash

undefined

Install dependencies

安装依赖

ddev composer install

Update all dependencies

更新所有依赖

ddev composer update

Update single package

更新单个包

ddev composer update typo3/cms-core --with-dependencies

Require new package (with v13/v14 dual compatibility)

安装新包（同时兼容v13/v14）

ddev composer require "vendor/package:^1.0"

Remove package

移除包

ddev composer remove vendor/package

Clear Composer cache

清空Composer缓存

ddev composer clear-cache

undefined

ddev composer clear-cache

undefined

Dual-Version Development

多版本兼容开发

For extensions supporting both v13 and v14:

bash

undefined

针对同时支持v13和v14的扩展开发：

bash

undefined

Set version constraint in extension's composer.json

在扩展的composer.json中设置版本约束

ddev composer require "typo3/cms-core:^13.0 || ^14.0" --no-update

undefined

ddev composer require "typo3/cms-core:^13.0 || ^14.0" --no-update

undefined

6. File Operations

6. 文件操作

SSH into Container

进入容器SSH

bash

undefined

bash

undefined

Web container (as www-data)

以www-data用户进入Web容器

ddev ssh

Web container (as root)

以root用户进入Web容器

ddev ssh -s web -u root

Database container

进入数据库容器

ddev ssh -s db

undefined

ddev ssh -s db

undefined

File Sync

文件同步

bash

undefined

bash

undefined

Copy file into container

在容器内复制文件

ddev exec cp /path/in/container /other/path

Copy from host to container

从主机复制文件到容器

docker cp localfile.txt ddev-myproject-web:/var/www/html/

Download file from container

从容器下载文件到主机

ddev exec cat /var/www/html/somefile > localfile

undefined

ddev exec cat /var/www/html/somefile > localfile

undefined

7. Debugging with Xdebug

7. 使用Xdebug调试

Enable/Disable

启用/禁用

bash

undefined

bash

undefined

Enable Xdebug

启用Xdebug

ddev xdebug on

Disable Xdebug (faster performance)

禁用Xdebug（提升性能）

ddev xdebug off

Check status

查看Xdebug状态

ddev xdebug status

undefined

ddev xdebug status

undefined

IDE Configuration (PhpStorm/Cursor)

IDE配置（PhpStorm/Cursor）

Set breakpoint in PHP file
Start listening for connections (PhpStorm: "Start Listening")
Enable Xdebug:
```
ddev xdebug on
```
Trigger request in browser
Debugger should connect

在PHP文件中设置断点
启动IDE的监听连接功能（PhpStorm："Start Listening"）
启用Xdebug：
```
ddev xdebug on
```
在浏览器中触发请求
调试器应自动连接

Xdebug Environment

Xdebug环境配置

yaml

undefined

yaml

undefined

.ddev/config.yaml

web_environment:

XDEBUG_MODE=debug,develop
XDEBUG_CONFIG=client_host=host.docker.internal

undefined

web_environment:

XDEBUG_MODE=debug,develop
XDEBUG_CONFIG=client_host=host.docker.internal

undefined

8. Multi-Site Configuration

8. 多站点配置

Additional Hostnames

额外主机名

yaml

undefined

yaml

undefined

.ddev/config.yaml

additional_hostnames:

site1
site2 additional_fqdns:
site1.myproject.ddev.site
site2.myproject.ddev.site

undefined

additional_hostnames:

site1
site2 additional_fqdns:
site1.myproject.ddev.site
site2.myproject.ddev.site

undefined

Site Configuration

站点配置

bash

undefined

bash

undefined

Create site configuration

创建站点配置目录

mkdir -p config/sites/site1


```yaml

mkdir -p config/sites/site1


```yaml

config/sites/site1/config.yaml

base: 'https://site1.myproject.ddev.site/' rootPageId: 1 languages:

title: English languageId: 0 locale: en_US.UTF-8

undefined

base: 'https://site1.myproject.ddev.site/' rootPageId: 1 languages:

title: English languageId: 0 locale: en_US.UTF-8

undefined

9. Services and Add-ons

9. 服务与附加组件

Common Add-ons

常用附加组件

bash

undefined

bash

undefined

Redis (for caching)

Redis（用于缓存）

ddev get ddev/ddev-redis

Elasticsearch

ddev get ddev/ddev-elasticsearch

Solr

ddev get ddev/ddev-solr

undefined

ddev get ddev/ddev-solr

undefined

Custom Services

自定义服务

yaml

undefined

yaml

undefined

.ddev/docker-compose.redis.yaml

services: redis: image: redis:7-alpine container_name: ddev-${DDEV_SITENAME}-redis command: redis-server --appendonly yes volumes: - redis-data:/data labels: com.ddev.site-name: ${DDEV_SITENAME} com.ddev.approot: $DDEV_APPROOT

volumes: redis-data:

undefined

services: redis: image: redis:7-alpine container_name: ddev-${DDEV_SITENAME}-redis command: redis-server --appendonly yes volumes: - redis-data:/data labels: com.ddev.site-name: ${DDEV_SITENAME} com.ddev.approot: $DDEV_APPROOT

volumes: redis-data:

undefined

Redis Caching Configuration (v13/v14)

Redis缓存配置（v13/v14）

php

<?php
// config/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['hash']['backend'] 
    = \TYPO3\CMS\Core\Cache\Backend\RedisBackend::class;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['hash']['options'] = [
    'hostname' => 'redis',
    'port' => 6379,
    'database' => 0,
];

php

<?php
// config/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['hash']['backend'] 
    = \TYPO3\CMS\Core\Cache\Backend\RedisBackend::class;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['hash']['options'] = [
    'hostname' => 'redis',
    'port' => 6379,
    'database' => 0,
];

10. Troubleshooting

10. 故障排查

Common Issues

常见问题解决

bash

undefined

bash

undefined

Restart everything

重启所有服务

ddev restart

Full reset (keeps database)

完全重置（保留数据库）

ddev stop && ddev start

Nuclear option (removes containers and database volume)

彻底清理（删除容器及数据库卷）

ddev delete -O && ddev start

View logs

查看日志

ddev logs

View specific service logs

查看指定服务的日志

ddev logs -s web ddev logs -s db

undefined

ddev logs -s web ddev logs -s db

undefined

Port Conflicts

端口冲突

bash

undefined

bash

undefined

Check what's using a port

检查端口占用情况

lsof -i :80

Use different ports in config.yaml

在config.yaml中使用其他端口

router_http_port: "8080" router_https_port: "8443"

undefined

router_http_port: "8080" router_https_port: "8443"

undefined

Permission Issues

权限问题

bash

undefined

bash

undefined

Fix file permissions

修复文件权限

ddev exec chmod -R g+w var/ ddev exec chmod -R g+w public/fileadmin/ ddev exec chmod -R g+w public/typo3temp/

undefined

ddev exec chmod -R g+w var/ ddev exec chmod -R g+w public/fileadmin/ ddev exec chmod -R g+w public/typo3temp/

undefined

11. Environment Variables

11. 环境变量

TYPO3 Context

TYPO3运行上下文

bash

undefined

bash

undefined

Development (default in DDEV)

开发环境（DDEV默认）

TYPO3_CONTEXT=Development

Production testing

生产测试环境

TYPO3_CONTEXT=Production

Sub-contexts

子上下文

TYPO3_CONTEXT=Development/Docker

undefined

TYPO3_CONTEXT=Development/Docker

undefined

Custom Variables

自定义变量

yaml

undefined

yaml

undefined

.ddev/config.yaml

web_environment:

MY_API_KEY=secret123
FEATURE_FLAG=enabled


Access in TYPO3:

```php
<?php
$apiKey = getenv('MY_API_KEY');
// or
$apiKey = $_ENV['MY_API_KEY'];

web_environment:

MY_API_KEY=secret123
FEATURE_FLAG=enabled


在TYPO3中访问：

```php
<?php
$apiKey = getenv('MY_API_KEY');
// 或者
$apiKey = $_ENV['MY_API_KEY'];

12. Best Practices

12. 最佳实践

Performance

性能优化

Disable Xdebug when not debugging (
```
ddev xdebug off
```
)
Use snapshots instead of full imports for quick state changes
Mount with Mutagen on macOS for better file sync performance
Use PHP 8.3 for best performance on v13/v14

调试完成后禁用Xdebug（
```
ddev xdebug off
```
）
使用快照替代完整数据库导入，快速切换开发状态
在macOS上使用Mutagen挂载以提升文件同步性能
使用PHP 8.3以获得v13/v14版本的最佳性能

Team Workflow

团队协作工作流

Commit
```
.ddev/config.yaml
```
to repository
Gitignore
```
.ddev/config.local.yaml
```
for personal overrides
Document additional setup steps in
```
README.md
```
Share database snapshots for consistent development data

提交
```
.ddev/config.yaml
```
到代码仓库
将
```
.ddev/config.local.yaml
```
加入.gitignore，用于个人自定义配置
在README.md中记录额外的安装步骤
共享数据库快照以保证开发数据一致性

Security

安全注意事项

Never expose DDEV ports publicly
Don't use DDEV in production
Rotate any sensitive data in development databases

不要公开暴露 DDEV端口
不要在生产环境中使用 DDEV
定期轮换开发数据库中的敏感数据

13. Multi-Version Testing (Extension Development)

13. 多版本测试（扩展开发）

When developing extensions that need to work across multiple TYPO3 versions:

当开发需要兼容多个TYPO3版本的扩展时：

Setup for Multi-Version Testing

多版本测试环境搭建

yaml

undefined

yaml

undefined

.ddev/config.yaml

name: my-extension type: php docroot: "" php_version: "8.3"

additional_hostnames:

v13
v14

undefined

name: my-extension type: php docroot: "" php_version: "8.3"

additional_hostnames:

v13
v14

undefined

Install Multiple TYPO3 Versions

安装多个TYPO3版本

bash

undefined

bash

undefined

Create version-specific directories

创建版本专属目录

mkdir -p v13 v14

Install TYPO3 v13

安装TYPO3 v13

cd v13 ddev composer create "typo3/cms-base-distribution:^13" cd ..

Install TYPO3 v14

安装TYPO3 v14

cd v14 ddev composer create "typo3/cms-base-distribution:^14" cd ..

Symlink extension

软链接扩展到各个版本目录

ln -s ../../../ v13/packages/my_extension ln -s ../../../ v14/packages/my_extension

undefined

ln -s ../../../ v13/packages/my_extension ln -s ../../../ v14/packages/my_extension

undefined

Access URLs

访问地址

Environment	URL
TYPO3 v13	`https://v13.my-extension.ddev.site/typo3/`
TYPO3 v14	`https://v14.my-extension.ddev.site/typo3/`

Default Credentials: admin / Joh316!

环境	地址
TYPO3 v13	`https://v13.my-extension.ddev.site/typo3/`
TYPO3 v14	`https://v14.my-extension.ddev.site/typo3/`

默认凭据：admin / Joh316!

Version-Specific Commands

版本专属命令

bash

undefined

bash

undefined

Run tests on v13

在v13环境运行测试

ddev exec -d /var/www/html/v13 vendor/bin/phpunit

Run tests on v14

在v14环境运行测试

ddev exec -d /var/www/html/v14 vendor/bin/phpunit

Clear cache for specific version

清空指定版本的缓存

ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush

---

ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush

---

Credits & Attribution

致谢与贡献

Thanks to Netresearch DTT GmbH for their contributions to the TYPO3 community.

感谢Netresearch DTT GmbH为TYPO3社区所做的贡献。

typo3-ddev

Original

Translation

TYPO3 DDEV Local Development

TYPO3 基于DDEV的本地开发

Container Priority

容器使用优先级

1. Project Initialization

1. 项目初始化

New TYPO3 Project (v14 - Preferred)

新建TYPO3项目（v14 - 推荐）

Create project directory

创建项目目录

Initialize DDEV with TYPO3 preset

使用TYPO3预设初始化DDEV

Start the environment

启动开发环境

Install TYPO3 v14 (preferred)

安装TYPO3 v14（推荐版本）

Run TYPO3 setup

运行TYPO3安装向导

New TYPO3 Project (v13 LTS)

新建TYPO3项目（v13 LTS）

Create project directory

创建项目目录

Initialize DDEV with TYPO3 preset

使用TYPO3预设初始化DDEV

Start the environment

启动开发环境

Install TYPO3 v13 LTS

安装TYPO3 v13 LTS版本

Run TYPO3 setup

运行TYPO3安装向导

Existing TYPO3 Project

现有TYPO3项目

Clone repository

克隆代码仓库

Configure DDEV (if not already)

配置DDEV（如果尚未配置）

Start and install dependencies

启动环境并安装依赖

Import database (see Database Operations)

导入数据库（详见数据库操作章节）

2. Recommended Configuration

2. 推荐配置

.ddev/config.yaml (v13/v14 Compatible)

.ddev/config.yaml（兼容v13/v14）

Fixed port for external tools (MySQL MCP, etc.)

为外部工具（如MySQL MCP等）设置固定端口

Enable Mailpit for email testing (replaced Mailhog in newer DDEV)

启用Mailpit进行邮件测试（在新版DDEV中替代了Mailhog）

PHP settings

PHP设置

Additional services

额外服务

.ddev/config.local.yaml (Personal Overrides)

.ddev/config.local.yaml（个人自定义配置）

Personal machine-specific overrides (gitignored)

针对个人机器的自定义配置（需加入.gitignore）

PHP Version Matrix

PHP版本对应表

3. Database Operations

3. 数据库操作

Import Database

导入数据库

From SQL file

从SQL文件导入

From gzipped file

从压缩的SQL文件导入

From remote (via SSH)

从远程服务器导入（通过SSH）

Export Database

导出数据库

Standard export

标准导出（压缩格式）

Without gzip

不压缩导出

Database Snapshots

数据库快照

Create snapshot before risky operation

`.ddev/config.yaml`
(v13/v14 Compatible)

`.ddev/config.yaml`
（兼容v13/v14）

`.ddev/config.local.yaml`
(Personal Overrides)

`.ddev/config.local.yaml`
（个人自定义配置）