你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

为 Azure 应用服务配置 PHP 应用

显示 PHP 版本

本指南介绍了如何在 Azure 应用服务中配置 PHP Web 应用、移动后端和 API 应用。

本指南为在应用服务中部署应用的 PHP 开发人员提供了重要概念和说明。 若从未使用过 Azure 应用服务,则首先应按照 PHP 快速入门以及将 PHP 与 MySQL 配合使用教程进行操作。

要显示当前的 PHP 版本,请在 Cloud Shell 中运行以下命令:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query phpVersion

注意

若要对开发槽进行寻址,请包含参数 --slot,后跟槽的名称。

要显示所有受支持的 PHP 版本,请在 Cloud Shell 中运行以下命令:

az webapp list-runtimes --os windows | grep PHP

本指南介绍了如何在 Azure 应用服务中配置 PHP Web 应用、移动后端和 API 应用。

本指南为在应用服务中部署应用的 PHP 开发人员提供了重要概念和说明。 若从未使用过 Azure 应用服务,则首先应按照 PHP 快速入门以及将 PHP 与 MySQL 配合使用教程进行操作。

要显示当前的 PHP 版本,请在 Cloud Shell 中运行以下命令:

az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

注意

若要对开发槽进行寻址,请包含参数 --slot,后跟槽的名称。

要显示所有受支持的 PHP 版本,请在 Cloud Shell 中运行以下命令:

az webapp list-runtimes --os linux | grep PHP

设置 PHP 版本

Cloud Shell 中运行以下命令,将 PHP 版本设置为 8.1:

az webapp config set --resource-group <resource-group-name> --name <app-name> --php-version 8.1

Cloud Shell 中运行以下命令,将 PHP 版本设置为 8.1:

az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "PHP|8.1"

运行编辑器

如果你希望应用服务在部署时运行编辑器,最简单的方式是在你的存储库中包括编辑器。

在本地终端窗口中,将目录更改为你的存储库根目录,并按照下载编辑器中的说明将 composer.phar 下载到目录根目录。

运行以下命令(需要安装 npm):

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

你的存储库根目录中现在有两个额外的文件:.deployment 和 deploy.sh。

打开 deploy.sh 并找到 节,该节如下所示:

##################################################################################################################################
# Deployment
# ----------

节的末尾添加运行必需工具所需的代码节:

# 4. Use composer
echo "$DEPLOYMENT_TARGET"
if [ -e "$DEPLOYMENT_TARGET/composer.json" ]; then
  echo "Found composer.json"
  pushd "$DEPLOYMENT_TARGET"
  php composer.phar install $COMPOSER_ARGS
  exitWithMessageOnError "Composer install failed"
  popd
fi

提交所有更改,并在启用了生成自动化的情况下使用 Git 或 Zip 部署来部署你的代码。 编辑器现在应作为部署自动化的一部分运行。

运行 Grunt/Bower/Gulp

如果你希望应用服务在部署时运行常用的自动化工具(例如 Grunt、Bower 或 Gulp),则你需要提供自定义部署脚本。 当你在启用了生成自动化的情况下通过 Git 或 Zip 部署进行部署时,应用服务会运行此脚本。

若要使你的存储库能够运行这些工具,需要将它们添加到 package.json 中的依赖项。例如:

"dependencies": {
  "bower": "^1.7.9",
  "grunt": "^1.0.1",
  "gulp": "^3.9.1",
  ...
}

在本地终端窗口中,将目录更改到你的存储库根目录,并运行以下命令(你需要安装 npm):

npm install kuduscript -g
kuduscript --node --scriptType bash --suppressPrompt

你的存储库根目录中现在有两个额外的文件:.deployment 和 deploy.sh。

打开 deploy.sh 并找到 节,该节如下所示:

##################################################################################################################################
# Deployment
# ----------

该节在末尾处运行 npm install --production。 在 节的末尾添加运行必需工具所需的代码节:

请参阅 MEAN.js 示例中的示例,其中的部署脚本也运行自定义 npm install 命令。

Bower

此代码片段运行 bower install

if [ -e "$DEPLOYMENT_TARGET/bower.json" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/bower install
  exitWithMessageOnError "bower failed"
  cd - > /dev/null
fi

Gulp

此代码片段运行 gulp imagemin

if [ -e "$DEPLOYMENT_TARGET/gulpfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/gulp imagemin
  exitWithMessageOnError "gulp failed"
  cd - > /dev/null
fi

Grunt

此代码片段运行 grunt

if [ -e "$DEPLOYMENT_TARGET/Gruntfile.js" ]; then
  cd "$DEPLOYMENT_TARGET"
  eval ./node_modules/.bin/grunt
  exitWithMessageOnError "Grunt failed"
  cd - > /dev/null
fi

自定义生成自动化

如果在启用了生成自动化的情况下使用 Git 或 zip 包部署应用,应用服务生成自动化将按以下顺序完成各个步骤:

  1. 运行 PRE_BUILD_SCRIPT_PATH 指定的自定义脚本。
  2. 运行 php composer.phar install
  3. 运行 POST_BUILD_SCRIPT_PATH 指定的自定义脚本。

PRE_BUILD_COMMANDPOST_BUILD_COMMAND 是默认为空的环境变量。 若要运行生成前命令,请定义 PRE_BUILD_COMMAND。 若要运行生成后命令,请定义 POST_BUILD_COMMAND

以下示例在一系列命令中指定两个以逗号分隔的变量。

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PRE_BUILD_COMMAND="echo foo, scripts/prebuild.sh"
az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings POST_BUILD_COMMAND="echo foo, scripts/postbuild.sh"

有关用于自定义生成自动化的其他环境变量,请参阅 Oryx 配置

有关应用服务如何在 Linux 中运行和构建 PHP 应用的详细信息,请参阅 Oryx 文档:如何检测和构建 PHP 应用

自定义启动

如果需要,可以通过在 Cloud Shell 中运行以下命令,在容器启动时运行自定义命令:

az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<custom-command>"

访问环境变量

在应用服务中,可以在应用代码外部设置应用设置。 然后,可以使用标准的 getenv() 模式访问这些设置。 例如,若要访问名为 DB_HOST 的应用设置,请使用以下代码:

getenv("DB_HOST")

更改站点根路径

所选的 Web 框架可能使用子目录作为站点根路径。 例如,Laravel 使用 public/ 子目录作为站点根路径。

若要自定义站点根路径,请使用 az resource update 命令设置应用的虚拟应用程序路径。 下面的示例将站点根路径设置为存储库中的 public/ 子目录。

az resource update --name web --resource-group <group-name> --namespace Microsoft.Web --resource-type config --parent sites/<app-name> --set properties.virtualApplications[0].physicalPath="site\wwwroot\public" --api-version 2015-06-01

默认情况下,Azure 应用服务将根虚拟应用程序路径 (/) 指向已部署的应用程序的文件的根目录 (sites\wwwroot)。

所选的 Web 框架可能使用子目录作为站点根路径。 例如,Laravel 使用 public/ 子目录作为站点根路径。

应用服务的默认 PHP 映像使用 Nginx,因此可以通过使用 root 指令配置 Nginx 服务器来更改站点根。 此示例配置文件包含以下代码片段,用于更改 root 指令:

server {
    #proxy_cache cache;
    #proxy_cache_valid 200 1s;
    listen 8080;
    listen [::]:8080;
    root /home/site/wwwroot/public; # Changed for Laravel

    location / {            
        index  index.php index.html index.htm hostingstart.html;
        try_files $uri $uri/ /index.php?$args; # Changed for Laravel
    }
    ...

默认容器使用在 /etc/nginx/sites-available/default 中找到的配置文件。 请记住,在应用重启时,你对此文件所做的任何编辑都将被清除。 若要在应用重启后进行有效的更改,请添加一个自定义启动命令,如以下示例所示:

cp /home/site/wwwroot/default /etc/nginx/sites-available/default && service nginx reload

此命令将默认的 Nginx 配置文件替换为存储库根目录中名为 default 的文件,并重启 Nginx。

检测 HTTPS 会话

在应用服务中,TLS/SSL 终止在网络负载均衡器上发生,因此所有 HTTPS 请求将以未加密的 HTTP 请求形式访问你的应用。 如果应用逻辑需要检查用户请求是否已加密,可以检查 X-Forwarded-Proto 标头。

if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
// Do something when HTTPS is used
}

使用常用 Web 框架可以访问采用标准应用模式的 X-Forwarded-* 信息。 在 CodeIgniter 中,is_https() 默认检查 X_FORWARDED_PROTO 的值。

自定义 php.ini 设置

如果需要对 PHP 安装进行更改,则可以按照以下步骤更改任何 php.ini 指令

注意

查看 PHP 版本和当前 php.ini 配置的最佳方法是在应用中调用 phpinfo()

自定义非 PHP_INI_SYSTEM 指令

若要自定义 PHP_INI_USER、PHP_INI_PERDIR 和 PHP_INI_ALL 指令(请参阅 php.ini 指令),请将 .user.ini 文件添加到应用的根目录中。

使用会在 php.ini 文件中使用的语法,将配置设置添加到 .user.ini 文件。 例如,如果希望启用 display_errors 设置,并将 upload_max_filesize 设置设为 10 分钟,则 .user.ini 文件应包含以下文本:

 ; Example Settings
 display_errors=On
 upload_max_filesize=10M

 ; Write errors to d:\home\LogFiles\php_errors.log
 ; log_errors=On

通过更改重新部署应用,然后重启该应用。

除了使用 .user.ini 文件之外,还可以在应用中使用 .user.ini 来自定义这些非 PHP_INI_SYSTEM 指令。

若要自定义 linux Web 应用(如 upload_max_filesize 和 expose_php)的 PHP_INI_USER、PHP_INI_PERDIR和PHP_INI_ALL指令,请使用自定义的“ini”文件。 可以在 SSH 会话中创建此文件。

  1. 转到你的 Kudu 站点 https://<sitename>.scm.azurewebsites.net。
  2. 从顶部菜单中选择 Bash 或 SSH。
  3. 在 Bash/SSH 中,转到“/home/site/wwwroot”目录。
  4. 创建名为“ini ”的目录(例如,mkdir ini)。
  5. 将当前工作目录更改为刚刚创建的“ini ”文件夹。

需要创建一个“ini”文件来添加你的设置。 在此示例中,使用“extensions.ini”。 没有文件编辑器(如 Vi、Vim 或 Nano),因此使用回显将设置添加到文件。 将“upload_max_filesize”从 2M 更改为 50M。 使用以下命令添加设置并创建“extensions.ini”文件(如果尚不存在)。

/home/site/wwwroot/ini>echo "upload_max_filesize=50M" >> extensions.ini
/home/site/wwwroot/ini>cat extensions.ini

upload_max_filesize=50M

/home/site/wwwroot/ini>

然后,转到 Azure 门户并添加应用程序设置来扫描刚刚创建的“ini”目录,以应用 upload_max_filesize 的更改。

  1. 转到 Azure 门户并选择你的应用服务 Linux PHP 应用程序。
  2. 为应用选择应用程序设置。
  3. 在“应用程序设置”部分下,选择“+ 添加新设置”。
  4. 对于“应用设置名称”,输入“PHP_INI_SCAN_DIR”,对于值,请输入“/home/site/wwwroot/ini”。
  5. 选择“保存”按钮。

注意

如果重新编译了 PHP 扩展(如 GD),请按照在 Azure 应用服务 - 添加 PHP 扩展中重新编译 PHP 扩展中的步骤操作

自定义 PHP_INI_SYSTEM 指令

若要自定义 PHP_INI_SYSTEM 指令(请参阅 php.ini 指令),请使用 PHP_INI_SCAN_DIR 应用设置。

首先,在 Cloud Shell 中运行以下命令,以添加名为 PHP_INI_SCAN_DIR 的应用设置:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PHP_INI_SCAN_DIR="d:\home\site\ini"

导航到 Kudu 控制台 (https://<app-name>.scm.azurewebsites.net/DebugConsole),然后导航到 d:\home\site

d:\home\site 中创建名为 ini 的目录,然后使用要自定义的指令在 d:\home\site\ini 目录中创建 .ini 文件(例如 settings.ini)。 使用将在 php.ini 文件中使用的相同语法。

例如,要更改 expose_php 的值,请运行以下命令:

cd /home/site
mkdir ini
echo "expose_php = Off" >> ini/setting.ini

需要重启应用才能使更改生效。

不能使用 .htaccess 方法自定义 PHP_INI_SYSTEM 指令(请参阅 php.ini 指令)。 应用服务使用 PHP_INI_SCAN_DIR 应用设置提供了一种单独的机制。

首先,在 Cloud Shell 中运行以下命令,以添加名为 PHP_INI_SCAN_DIR 的应用设置:

az webapp config appsettings set --name <app-name> --resource-group <resource-group-name> --settings PHP_INI_SCAN_DIR="/usr/local/etc/php/conf.d:/home/site/ini"

/usr/local/etc/php/conf.d 是 php.ini 所在的默认目录。 /home/site/ini 是自定义目录,你将在其中添加自定义 .ini 文件。 使用 : 分隔值。

使用 Linux 容器导航到 Web SSH 会话 (https://<app-name>.scm.azurewebsites.net/webssh/host)。

/home/site 中创建名为 ini 的目录,然后使用要自定义的指令在 /home/site/ini 目录中创建 .ini 文件(例如 settings.ini)。 使用将在 php.ini 文件中使用的相同语法。

提示

在应用服务中的内置 Linux 容器中,/home 用作持久性共享存储。

例如,要更改 expose_php 的值,请运行以下命令:

cd /home/site
mkdir ini
echo "expose_php = Off" >> ini/setting.ini

需要重启应用才能使更改生效。

启用 PHP 扩展

内置 PHP 安装包含最常用的扩展。 可以按照与自定义 php.ini 指令相同的方式来启用其他扩展。

注意

查看 PHP 版本和当前 php.ini 配置的最佳方法是在应用中调用 phpinfo()

若要启用其他扩展,请执行下列步骤:

在应用的根目录中添加 bin 目录,并在其中放入 .dll 扩展文件(例如 mongodb.dll)。 确保扩展与 Azure 中的 PHP 版本兼容,并且与 VC9 和非线程安全 (nts) 兼容。

部署所做的更改。

按照自定义 PHP_INI_SYSTEM 指令中的步骤操作,使用 extensionzend_extension 指令将扩展添加到自定义 .ini 文件中。

extension=d:\home\site\wwwroot\bin\mongodb.dll
zend_extension=d:\home\site\wwwroot\bin\xdebug.dll

需要重启应用才能使更改生效。

内置 PHP 安装包含最常用的扩展。 可以按照与自定义 php.ini 指令相同的方式来启用其他扩展。

注意

查看 PHP 版本和当前 php.ini 配置的最佳方法是在应用中调用 phpinfo()

若要启用其他扩展,请执行下列步骤:

在应用的根目录中添加 bin 目录,并将 .so 扩展文件放入其中(例如 mongodb.so)。 确保扩展与 Azure 中的 PHP 版本兼容,并且与 VC9 和非线程安全 (nts) 兼容。

部署所做的更改。

按照自定义 PHP_INI_SYSTEM 指令中的步骤操作,使用 extensionzend_extension 指令将扩展添加到自定义 .ini 文件中。

extension=/home/site/wwwroot/bin/mongodb.so
zend_extension=/home/site/wwwroot/bin/xdebug.so

需要重启应用才能使更改生效。

访问诊断日志

使用标准 error_log() 实用工具使诊断日志显示在 Azure 应用服务中。

若要在应用服务中从应用程序代码内部访问生成的控制台日志,请在 Cloud Shell 中运行以下命令,打开诊断日志记录:

az webapp log config --resource-group <resource-group-name> --name <app-name> --docker-container-logging filesystem --level Verbose

--level 的可能值为:ErrorWarningInfoVerbose。 每个后续级别包括上一个级别。 例如:Error 仅包含错误消息,Verbose 则包含所有消息。

启用诊断日志记录功能以后,请运行以下命令来查看日志流:

az webapp log tail --resource-group <resource-group-name> --name <app-name>

如果没有立即看到控制台日志,请在 30 秒后重新查看。

注意

也可通过浏览器在 https://<app-name>.scm.azurewebsites.net/api/logs/docker 中检查日志文件。

若要随时停止日志流式处理,请键入 Ctrl+C

可以访问在容器中生成的控制台日志。

首先,请运行以下命令,以便启用容器日志记录功能:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

<app-name><resource-group-name> 替换为适合 Web 应用的名称。

启用容器日志记录功能以后,请运行以下命令来查看日志流:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

如果没有立即看到控制台日志,请在 30 秒后重新查看。

若要随时停止日志流式处理,可键入 CtrlC。

也可通过浏览器在 https://<app-name>.scm.azurewebsites.net/api/logs/docker 中检查日志文件。

疑难解答

如果运行中的 PHP 应用在应用服务中的行为不同或有错误,请尝试执行以下操作:

  • 访问日志流
  • 在生产模式下,在本地测试应用。 应用服务在生产模式下运行你的应用,因此你需要确保项目在生产模式下按预期在本地运行。 例如:
    • 根据 composer.json,可以为生产模式安装不同的包(require-dev)。
    • 某些 Web 框架可以在生产模式下通过各种方式部署静态文件。
    • 在生产模式下运行时,某些 Web 框架可能会使用自定义的启动脚本。
  • 在调试模式下,在应用服务中运行应用。 例如,在 Laravel 中,可以通过APP_DEBUG 应用设置设置为 true以将应用配置为在生产环境中输出调试消息。

日志中的 robots933456

你可能会在容器日志中看到以下消息:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

可以放心忽略此消息。 /robots933456.txt 是一个虚拟 URL 路径,应用服务使用它来检查容器能否为请求提供服务。 404 响应只是指示该路径不存在,但它让应用服务知道容器处于正常状态并已准备就绪,可以响应请求。

后续步骤

或者参阅其他某些资源:

环境变量和应用设置参考