typo3-ddev

TYPO3 DDEV 设置技能

关键：URL 方案

绝不猜测 URL。读取 .ddev/config.yaml 中的 name:，然后应用子域名模式：

https://v{VERSION}.{sitename}.ddev.site/typo3/ — 例如，https://v14.my-ext.ddev.site/typo3/

首页：https://{sitename}.ddev.site/ · 文档：https://docs.{sitename}.ddev.site/

每个版本都通过 additional_hostnames 配置 Apache 虚拟主机（/var/www/html/v{VERSION}）。绝不能根据目录列表推断 URL。

凭据：admin / Joh316!!

容器优先级

1. 存在 .ddev/ → ddev exec
2. 存在 docker-compose.yml → docker compose exec
3. 只有在没有容器时才使用系统工具。使用项目配置的 PHP。

**在容器内编辑文件：**使用 docker cp 复制文件，再运行 ddev exec — 不要使用 heredoc/php -r。参见 references/container-file-editing.md。

快速开始

ddev start && ddev install-all    # All versions (11/12/13/14)
ddev install-v14                  # v14.3 LTS (default / gold standard)
ddev install-v13                  # v13.4 LTS

数据库选择

MariaDB 10.11（默认）· SQLite（简单，无需 SQL）· PostgreSQL 16（GIS）· MySQL 8.0（与 Oracle 保持一致）。参见 references/advanced-options.md references/0002-mariadb-default-with-database-alternatives.md。

PHP 管理

在 config.yaml 中设置 php_version: "8.3"。通过 .ddev/web-build/Dockerfile 升级（apt-get dist-upgrade）。自定义设置：.ddev/php/custom.ini。参见 references/0003-php-version-management.md。

TYPO3 版本差异

	v12	v13	v14.3 LTS
设置	install:setup --use-existing-database	setup	setup
激活	自动（Composer）	extension:setup	extension:setup
composer.json	可选	可选	必需（经典模式，#108310）
默认主题	bootstrap-package	bootstrap-package	Camino（#108539）
Fluid	2.x	4.x	5.x 严格模式（#108148）
CKEditor	41–42	41–42	47

参见 references/typo3-12-cli-changes.md。

设置后验证

ddev status、ddev describe、ddev exec -d /var/www/html/v13 vendor/bin/typo3 extension:list --active。参见 references/post-setup-verification.md。

可选服务和命令

• Valkey 8（默认）或 Redis 7：references/0001-valkey-default-with-redis-alternative.md
• Ofelia 调度器：TYPO3 调度器自动化
• ddev generate-makefile / ddev generate-index / ddev docs
• ddev xdebug on · 清理缓存：参见“故障排除”

扩展命名

Composer 使用连字符（nr-llm），TYPO3 键使用下划线（nr_llm）。来源：composer.json 中的 name。

故障排除

问题	解决方案
端口冲突	router_http_port: "8080" / router_https_port: "8443"
数据库已存在	ddev mysql -e "DROP DATABASE v13; CREATE DATABASE v13;"
找不到扩展	ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush
Windows 健康检查	使用 php-fpm.sock 添加 /phpstatus 端点
PCOV/pecl 失败	apt-get install php${PHP_VERSION}-pcov
PHP 设置未生效	放置在 .ddev/php/custom.ini 中
完全清理	运行 ddev delete --omit-snapshot --yes，然后删除 Docker 卷

参考资料

主题	文件
前置条件	references/prerequisites-validation.md
快速开始	references/quickstart.md
高级选项	references/advanced-options.md
设置后	references/post-setup-verification.md
品牌/首页	references/index-page-generation.md
ADR 参考资料	references/{0001,0002,0003}-*.md
Windows	references/windows-fixes.md、references/windows-optimizations.md
文档渲染	references/documentation-rendering.md
故障排除	references/troubleshooting.md

---

署名与致谢

本技能基于 Netresearch DTT GmbH 的出色工作。

原始仓库：https://github.com/netresearch/typo3-ddev-skill

Copyright (c) Netresearch DTT GmbH — 方法论与最佳实践（MIT / CC-BY-SA-4.0）

特别感谢 Netresearch DTT GmbH 为 TYPO3 社区慷慨贡献开源成果，助力打造了这套技能集合。 由 webconsulting.at 为这套技能集合改编