Ddev项目启动失败：web服务异常、健康检查超时，如何调试？

遇到这种web服务不健康的问题，我通常会按下面的步骤一步步排查，大概率能找到根源：

1. 先看Web容器的启动日志（最关键！） #

健康检查超时99%是因为web服务本身没启动起来，直接看日志就能定位问题：

ddev logs -s web

重点盯紧日志里的错误信息，比如Apache/Nginx的配置语法错误、PHP扩展安装失败、文件权限异常这些，都是常见的元凶。

2. 直接进入Web容器手动调试 #

如果日志里的信息不够明确，直接进到容器里现场排查：

ddev ssh -s web

进去后可以尝试手动启动web服务，看具体报错：

• 用Apache的话：执行apache2ctl configtest检查配置语法，再用apache2ctl start尝试启动
• 用Nginx的话：先nginx -t验证配置，再nginx start启动服务
  同时可以检查关键目录的权限，比如/var/www/html的权限是否正常，有没有缺失项目必要的文件。

3. 排查自定义配置是否出错 #

如果你最近修改过.ddev里的自定义配置（比如web-build目录的Dockerfile、apache/nginx目录的自定义.conf文件），很可能是这些配置出了问题。

先临时禁用自定义配置试试：

# 备份自定义配置，避免丢失
mv .ddev/web-build .ddev/web-build.bak
mv .ddev/apache .ddev/apache.bak
mv .ddev/nginx .ddev/nginx.bak

然后重新执行ddev start，如果能正常启动，说明问题就出在你刚才备份的自定义配置里，逐个排查修改即可。

4. 检查Docker环境状态 #

有时候Docker本身的异常也会导致服务出问题：

• 先重启Docker服务：Linux用systemctl restart docker，Windows/macOS在Docker Desktop里点重启按钮
• 用docker ps -a查看web容器的状态，是不是一直在循环重启？如果是，结合之前的日志找循环重启的原因
• 检查Docker资源是否充足：比如内存分配太少，导致服务启动失败（Docker Desktop里可以在设置里调整资源配额）

5. 清理Ddev缓存与旧容器 #

残留的旧容器或缓存也可能引发奇怪的问题：

# 停止所有Ddev项目
ddev stop -a
# 清理缓存和旧容器（不会删除项目代码与数据库数据）
ddev cleanup

如果还是不行，可以尝试删除所有项目容器（注意：这会删除容器，但项目代码和数据库数据不会丢失，保险起见可以先备份数据库）：

ddev delete -a

然后重新启动项目。

6. 检查Ddev版本兼容性 #

如果你最近升级了Ddev，或者项目用的Ddev版本比较旧，可能存在兼容性问题：

• 用ddev version查看当前版本，尝试升级到最新稳定版，或者回退到之前能正常运行的版本试试

7. 排查PHP版本与依赖 #

如果最近修改了项目的PHP版本（在.ddev/config.yaml里的php_version），可能出现依赖的PHP扩展没安装成功的情况，看web日志里有没有类似“extension not found”的错误，调整PHP版本或者通过web-build里的Dockerfile手动安装扩展。

如果以上步骤都试过还是没解决，把ddev logs -s web里的关键错误信息贴出来，就能更精准地定位问题了。

内容的提问来源于stack exchange，提问作者rfay