Dokku部署PHP应用异常：构建完成但无法访问应用

Hey there, let's figure out why your PHP app isn't accessible even though the build completes successfully. Since your Django apps are running fine on the same Dokku instance, we can focus on PHP-specific deployment details that might be off. Here's a step-by-step breakdown to diagnose the issue:

1. Check if Your App Processes Are Actually Running #

First, confirm that your app's processes aren't crashing silently after deployment:

• Run dokku ps:status <your-app-name> to see the current state of your app's processes. Look for "running" status—if it's "crashing" or "exited", that's a red flag.
• Pull the real-time logs with dokku logs <your-app-name> --tail to spot any startup errors, missing dependencies, or runtime crashes. Common issues here include PHP-FPM failing to start or misconfigured environment variables breaking the app.

2. Validate Your Procfile #

Dokku relies on the Procfile to know how to start your app, and PHP apps have specific requirements here:

• Make sure your Procfile uses the correct command for your project structure. For most PHP frameworks (like Laravel, Symfony), the standard command is:

  web: vendor/bin/heroku-php-nginx public/
  

  This tells Dokku to use the Heroku PHP buildpack's nginx+PHP-FPM setup, pointing to the public/ directory (where your index.php entry point lives).
• Test the Procfile command locally first—if it doesn't start your app on your machine, it won't work on Dokku either.

3. Verify Port Binding & Dokku Proxy Configuration #

Dokku uses a reverse proxy to route traffic to your app, so incorrect port binding will break access:

• Your PHP app must bind to the port specified by the $PORT environment variable, not a hardcoded port. The heroku-php-nginx command handles this automatically, but if you're using a custom startup script, double-check that it respects $PORT.
• Run dokku proxy:report <your-app-name> to confirm the proxy is configured to map traffic to your app's port. Look for entries like proxy enabled: true and the correct port mapping.

4. Check Environment Variables & .env File #

Dokku doesn't automatically load .env files by default, which can break apps that rely on these variables:

• Instead of relying on .env, use dokku config:set <your-app-name> KEY=VALUE to manually set critical variables (like database credentials, APP_URL, or debug modes).
• If you need to load .env automatically, you can use the dokku-env plugin, but note that compatibility with Dokku 0.5.4 may vary—test it carefully if you go this route.

5. Confirm Dependencies & PHP Extensions #

A successful build doesn't always mean all dependencies are properly installed or compatible:

• Run dokku run <your-app-name> composer install --no-dev to re-install dependencies and check for any missing packages or compatibility errors.
• Verify that your project's required PHP extensions (like php-mbstring, php-pdo, php-gd) are installed. You can check available extensions with dokku run <your-app-name> php -m. If any are missing, you can specify them in a .buildpacks file or use a custom buildpack that includes them.
• Ensure your project's PHP version matches what Dokku is using. Create a .php-version file in your project root (e.g., 7.4) to specify the exact version if needed.

6. Inspect Nginx Configuration (For Heroku PHP Buildpack Users) #

If you're using the official Heroku PHP buildpack, Dokku generates an nginx config for your app—misconfigurations here can block access:

• Run dokku run <your-app-name> cat /app/.heroku/php/etc/nginx.conf to view the generated config. Check that the root directive points to your app's public directory, and that rewrite rules (like for Laravel's clean URLs) are present:

  location / {
      try_files $uri $uri/ /index.php?$query_string;
  }
  

  If the config is missing these rules, your app might return 404 errors even if the process is running.

Once you work through these steps, you should be able to pinpoint why your PHP app isn't loading. Start with the logs and process status—those usually give the clearest clues!

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