mcpField
T
typo3-ddev

typo3-ddev

github.com/netresearch云与 DevOps844 次安装3 天前更新
代码仓库

关于 typo3-ddev

面向使用 DDEV 的 TYPO3 项目的配置与故障排查指南，涵盖各版本安装、数据库、PHP 设置和验证，也说明无 DDEV 环境的部署路径。

主要功能

  1. 01基于 DDEV 配置 TYPO3
  2. 02按版本区分安装步骤
  3. 03数据库与 PHP 配置
  4. 04安装后检查
  5. 05无 DDEV 环境部署
  6. 06故障排查指南

适用场景

  1. 01在本地配置不同版本的 TYPO3
  2. 02选择并配置数据库
  3. 03验证安装状态与登录路由
  4. 04在无 DDEV 环境部署 TYPO3

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/netresearch/typo3-ddev-skill --skill typo3-ddev

安装后在 Claude Code 中输入/typo3-ddev确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/templates/
.envrc
config.redis.php.example
config.yaml
docker-compose.git-info.yaml
docker-compose.ofelia.yaml.optional
docker-compose.services-redis.yaml.optional
docker-compose.services.yaml.optional
docker-compose.web.yaml
index.html.netresearch.template
index.html.typo3.template
Makefile.template
assets/templates/apache/
apache-site.conf
docs.conf
v11.conf
v12.conf
v13.conf
v14.conf
assets/templates/commands/
install-all
install-v11
install-v12
install-v13
install-v14
assets/templates/commands/host/
docs
pre-start-git-info
setup
assets/templates/commands/web/
configure-extension.optional
generate-index
generate-makefile
install-introduction.optional
assets/templates/homeadditions/
.bashrc_additions.optional

详细介绍

TYPO3 DDEV 设置技能

关键：URL 方案

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

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

每个版本都会通过 additional_hostnames 获取一个虚拟主机（/var/www/html/v{VERSION}）。切勿根据目录列表推断 URL。

凭据：admin / Joh316!!

容器优先级

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

无法使用 DDEV（CI、容器、Agent 测试环境——DDEV 负责驱动 Docker）：读取 .ddev/config.yaml 和 .ddev/commands/，然后运行 scripts/provision-without-ddev.sh --extension . --serve。该发行版不包含 .htaccess，因此 /typo3/ 返回 200，而子路由返回 404——参见 references/without-ddev.md。

在容器内编辑：使用 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 · PostgreSQL 16 · MySQL 8.0。参见 references/advanced-options.md、references/0002-mariadb-default-with-database-alternatives.md。

PHP 管理

在 config.yaml 中设置 php_version: "8.3"。通过 .ddev/web-build/Dockerfile 升级。设置文件：.ddev/php/custom.ini。参见 references/0003-php-version-management.md。

TYPO3 版本差异

v12v13v14.3 LTS
设置install:setup --use-existing-databasesetupsetup
激活自动extension:setupextension:setup
composer.json可选可选必需 (#108310)
主题bootstrap-packagebootstrap-packageCamino (#108539)
Fluid2.x4.x5.x 严格模式 (#108148)
CKEditor41–4241–4247

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

设置后验证

运行 ddev status、ddev describe、ddev exec -d /var/www/html/v13 vendor/bin/typo3 extension:list --active。检查实际结果，而不只是状态：/typo3/login 必须返回 200。参见 references/post-setup-verification.md。

可选服务和命令

  • Valkey 8（默认）或 Redis 7：references/0001-valkey-default-with-redis-alternative.md
  • Ofelia：调度器自动化 · ddev generate-makefile / generate-index / docs / 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 端点
PHP 设置未生效.ddev/php/custom.ini
完全清理ddev delete --omit-snapshot --yes，删除卷

参考资料

主题references/ 中的文件
不使用 DDEVwithout-ddev.md
前提条件、快速开始{prerequisites-validation,quickstart}.md
高级选项、设置后验证、品牌{advanced-options,post-setup-verification,index-page-generation}.md
ADR · Windows{0001,0002,0003}-*.md · windows-{fixes,optimizations}.md
文档渲染、故障排除{documentation-rendering,troubleshooting}.md

评论

支持 Markdown