本教程旨在解决在Azure App Service上运行PHP应用时，因`pdo_mysql`驱动未启用而导致的500错误。文章将详细阐述不同PHP环境（SSH、Kudu Bash、Web服务器）的配置差异，并提供在Azure App Service Linux环境下通过自定义`php.ini`文件和应用设置来正确启用`pdo_mysql`驱动的步骤，包括配置示例、验证方法及注意事项，确保您的Laravel或其他PHP应用能够顺利连接MySQL数据库。
在Azure App Service上部署PHP应用程序（如Laravel 8）时，开发者可能会遇到一个常见问题：本地运行正常的应用，在部署到Azure后，凡是涉及数据库查询的页面都会返回PHP 500错误。经过排查，这通常是由于服务器环境中缺少或未启用pdo_mysql驱动所致。更令人困惑的是，在Azure提供的SSH终端中执行php -m命令可能显示pdo_mysql已启用，但在Kudu远程执行终端（Bash终端）或Oryx构建过程中，该模块却未显示，导致应用无法正常运行。
理解PHP环境差异
这种SSH与Kudu/Bash终端输出不一致的现象，揭示了Azure App Service中存在多个PHP运行环境，且它们可能加载不同的配置文件。
- SSH终端环境： 通常指向App Service宿主机上的PHP CLI环境，可能已经预装并启用了pdo_mysql。
- Kudu Bash终端/Oryx构建环境： 这些环境用于部署、构建和执行特定脚本，它们使用的PHP CLI配置可能与SSH环境不同，也可能与Web服务器（FPM）环境不同。当Oryx构建器报告pdo_mysql缺失时，意味着构建时的PHP CLI环境不包含此驱动。
- Web服务器（FPM）环境： 这是实际运行您的Web应用程序的PHP环境。如果此环境未启用pdo_mysql，您的应用程序将无法连接数据库，从而导致500错误。解决此问题是首要任务。
启用pdo_mysql驱动的核心步骤
要在Azure App Service Linux上为Web应用程序启用pdo_mysql驱动，主要方法是提供一个自定义的php.ini文件，并确保Web服务器环境加载它。
1. 创建或修改自定义 php.ini 文件
首先，您需要在应用程序的根目录（通常是/home/site/wwwroot）中创建一个名为php.ini的文件，或者修改现有文件。
示例代码：
; php.ini example for Azure App Service ; Enable the pdo_mysql extension extension=pdo_mysql.so ; Optional: You might also want to set other PHP directives here. ; For example, to control error display and logging: ; display_errors = Off ; log_errors = On ; error_log = /home/LogFiles/php_errors.log ; upload_max_filesize = 128M ; post_max_size = 128M
请确保extension=pdo_mysql.so这一行存在且没有被注释掉（即前面没有分号;）。
2. 配置Azure App Service加载自定义 php.ini
创建php.ini文件后，需要通过Azure App Service的“配置”设置，告知PHP运行时加载这个自定义文件。
- 导航到Azure门户： 打开您的Azure App Service资源。
- 选择“配置”： 在左侧导航栏中找到“配置”选项。
- 添加新的应用程序设置： 在“应用程序设置”选项卡下，点击“新建应用程序设置”。
-
设置键值对：
- 名称 (Name)： WEBSITES_PHP_ARGS
- 值 (Value)： -c /home/site/wwwroot/php.ini 这个设置会指示PHP运行时使用指定路径的php.ini文件作为其主配置文件。
注意事项：
- 如果您将php.ini文件放置在wwwroot的子目录中，请相应地调整路径。
- 对于某些PHP版本或配置，可能还需要extension_dir指令来指定扩展库的路径。然而，在Azure App Service Linux上，通常pdo_mysql.so已在默认的扩展目录中，无需额外设置。
验证配置
完成上述步骤后，您需要验证pdo_mysql是否已成功启用。
1. 通过 phpinfo() 检查
创建一个简单的info.php文件，并将其放置在wwwroot目录下：
示例代码：
部署此文件后，通过浏览器访问https://your-app-name.azurewebsites.net/info.php。在输出页面中搜索“pdo_mysql”或“PDO drivers”。如果看到pdo_mysql驱动已启用，则表示配置成功。完成验证后，请务必删除或禁用info.php文件，以避免泄露敏感信息。
2. 在Kudu Bash终端中检查 (可选)
虽然主要目标是为Web服务器启用驱动，但您也可以在Kudu Bash终端中尝试再次运行php -m。即使此时pdo_mysql仍然不显示，只要您的Web应用程序能够正常运行并连接数据库，就说明Web服务器环境的配置已成功。Kudu Bash环境的PHP CLI可能不会加载WEBSITES_PHP_ARGS指定的php.ini。
3. 测试应用程序
最后，也是最重要的验证步骤，是直接测试您的应用程序。访问之前导致500错误的页面，如果它们现在能够正常显示并与数据库交互，则说明问题已解决。
注意事项
- 重启App Service： 每次修改应用程序设置或上传新的php.ini文件后，建议重启您的Azure App Service，以确保所有更改都已生效。
- 日志排查： 如果问题仍然存在，请检查Azure App Service的诊断日志（可在Kudu控制台的LogFiles目录中找到，或通过Azure门户的“诊断和解决问题”功能查看）。PHP错误日志（如果已在php.ini中配置error_log）将提供更详细的错误信息。
- Oryx构建问题： 如果Oryx构建器在部署时仍然抱怨pdo_mysql缺失，这通常意味着构建过程中的PHP CLI环境配置与运行时环境不同。解决此问题可能需要更高级的自定义部署脚本，例如在构建过程中动态安装或配置PHP扩展，但这超出了本文主要解决运行时500错误的范围。对于大多数应用而言，只要运行时环境配置正确，构建时的警告可能不会影响最终应用的功能。
- PHP版本兼容性： 确保pdo_mysql.so模块与您的PHP版本兼容。Azure App Service通常会预装兼容的扩展。
总结
在Azure App Service中解决pdo_mysql驱动缺失导致的500错误，关键在于理解不同PHP环境的配置差异，并针对Web服务器运行时环境进行精确配置。通过在/home/site/wwwroot目录下创建自定义php.ini文件并添加extension=pdo_mysql.so，然后通过WEBSITES_PHP_ARGS应用程序设置指向该文件，可以有效地启用所需的数据库驱动。务必在更改后重启App Service并进行彻底验证，以确保您的PHP应用程序能够稳定、高效地运行。
