為 Azure App Service 設定 PHP 應用程式

發行項
03/11/2024

顯示 PHP 版本

警告

Windows 上的 PHP 於 2022 年 11 月達到生命週期結束，且僅在 Linux 上的 App Service 上受到支援。本文僅供參考。.

本指南說明如何在 Azure App Service 中設定 PHP Web 應用程式、行動後端和 API 應用程式。

本指南為將應用程式部署至 App Service 的 PHP 開發人員提供了重要概念和指示。如果您從未使用過 Azure App Service，請先遵循 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 App Service 中設定 PHP Web 應用程式、行動後端和 API 應用程式。

若要顯示目前的 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

如果您想要讓 App Service 在部署階段執行 Composer，最簡單的方式就是將 Composer 包含在存放庫中。

在本機終端機視窗中，將目錄切換至存放庫根目錄，並依照下載 Composer 中的指示，將 composer.phar 下載至根目錄。

執行下列命令 (您需要安裝 npm)：

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

您的存放庫根目錄現在有兩個額外的檔案：.deployment 和 deploy.sh。

開啟 deploy.sh 並尋找 Deployment 區段，如下所示：

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

在 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 部署) 來部署程式碼。 Composer 現在應該會在部署自動化的過程中執行。

執行 Grunt/Bower/Gulp

如果您想要讓 App Service 在部署階段執行熱門的自動化工具 (例如 Grunt、Bower 或 Gulp)，您必須提供自訂部署指令碼。當您使用 Git (或在已啟用組建自動化的情況下使用 Zip 部署) 進行部署時，App Service 會執行此指令碼。

若要讓存放庫執行這些工具，您必須將那些工具新增至 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 區段，如下所示：

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

此區段最後會執行 npm install --production。在 Deployment 區段的「結尾」新增您執行必要工具所需的程式碼區段：

Bower
Gulp
Grunt

請參閱 MEAN.js 樣本中的範例，其中，deployment 指令碼也執行自訂 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 套件) 來部署應用程式，App Service 組建自動化將會依下列順序逐步執行：

執行自訂指令碼 (如果 PRE_BUILD_SCRIPT_PATH 已指定)。
執行 php composer.phar install。
執行自訂指令碼 (如果 POST_BUILD_SCRIPT_PATH 已指定)。

PRE_BUILD_COMMAND 和 POST_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 設定。

若要深入了解 App Service 如何在 Linux 中執行和建置 PHP 應用程式，請參閱 Oryx 文件：如何偵測和建置 PHP 應用程式。

自訂啟動

如有需要，您可以在容器啟動時執行自訂命令，方法是在 Cloud Shell 中執行下列命令：

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

存取環境變數

在 App Service 中，您可以於應用程式的程式碼外部設定應用程式設定。然後，您可以使用標準的 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 App Service 會將根虛擬應用程式路徑 (/) 指向已部署應用程式檔案的根目錄 (sites\wwwroot)。

您選擇的 web 架構可能會使用子目錄作為網站根目錄。例如，Laravel 使用 public/ 子目錄作為網站根目錄。

App Service 的預設 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 組態檔取代為存放庫根目錄中名為預設的檔案，然後重新啟動 Nginx。

偵測 HTTPS 工作階段

在 App Service 中，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 設定設為 10M，則 .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 之外，您還可以在應用程式中使用 ini_set() 來自訂這些非 PHP_INI_SYSTEM 指示詞。

若要自訂 linux Web 應用程式的 PHP_INI_USER、PHP_INI_PERDIR 和 PHP_INI_ALL 指示詞，例如 upload_max_filesize 和 expose_php，請使用自訂的 “ini” 檔案。您可以在 SSH 工作階段中加以建立。

移至 KUDU 網站 https://<sitename>.scm.azurewebsites.net。
從頂端功能表中選取 [Bash] 或 [SSH]。
在 Bash/SSH 中，移至 "/home/site/wwwroot" 目錄。
建立名為 "ini" 的目錄 (例如 mkdir ini)。
將目前的工作目錄變更為您剛建立的 "ini" 資料夾。

您必須建立 "ini" 檔案，才能將設定新增至其中。在此範例中，我們使用 "extensions.ini"。沒有檔案編輯器，例如 Vi、Vim 或 Nano，因此您將使用 echo 將設定新增至該檔案。將 "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 入口網站並新增應用程式設定，以掃描您剛建立以套用 upload_max_filesize 變更的 “ini” 目錄。

前往 Azure 入口網站，然後選取 App Service Linux PHP 應用程式。
選取應用程式的 [應用程式設定]。
在 [應用程式設定] 區段下，選取 [+ 新增設定]。
針對應用程式設定名稱，輸入 “PHP_INI_SCAN_DIR”，針對值，輸入 “/home/site/wwwroot/ini”。
選取 [儲存] 按鈕。

注意

如果您重新編譯 PHP 延伸模組，例如 GD，請遵循在 Azure App Service 重新編譯 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

如果要讓變更生效，請重新啟動應用程式。

若要自訂 PHP_INI_SYSTEM 指示詞 (請參閱 php.ini 指示詞)，您不能使用 .htaccess 方法。 App Service 會使用 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 容器 (https://<app-name>.scm.azurewebsites.net/webssh/host) 瀏覽至 web SSH 工作階段。

在 /home/site 中建立名為 ini 的目錄，然後使用要自訂的指示詞在 /home/site/ini 目錄中建立 .ini 檔案 (例如 settings.ini)。使用要在 php .ini 檔案中使用的相同語法。

提示

在 App Service 的內建 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 指示詞中的步驟，將擴充功能新增至使用 extension 或 zend_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 指示詞中的步驟，將擴充功能新增至使用 extension 或 zend_extension 指示詞的自訂 .ini 檔案。

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

如果要讓變更生效，請重新啟動應用程式。

存取診斷記錄

使用標準 error_log() 公用程式，使您的診斷記錄顯示在 Azure App Service 中。

若要存取 App Service 中應用程式程式碼內部產生的主控台記錄，請在 Cloud Shell 中執行下列命令，以開啟診斷記錄功能：

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

--level 的可能值為：Error、Warning、Info 和 Verbose。後續的每個層級都包含上一個層級。例如：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

以適合您 Web 應用程式的名稱取代 <app-name> 和 <resource-group-name>。

開啟容器記錄後，請執行下列命令來查看記錄資料流：

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

如果您沒有立即看到主控台記錄，請在 30 秒後再查看。

若要隨時停止記錄資料流，請輸入 Ctrl+C。

您也可以在瀏覽器中的 https://<app-name>.scm.azurewebsites.net/api/logs/docker 檢查記錄檔。

疑難排解

當運作中的 PHP 應用程式在 App Service 中有不同的行為或發生錯誤時，請嘗試下列動作：

存取記錄資料流。
在生產模式中於本機測試應用程式。 App Service 會在生產模式中執行您的應用程式，因此您必須確定專案在生產模式下按預期在本機中運作。例如：
- 視 composer.json 而定，可能會為生產模式安裝不同的套件 (require 與 require-dev)。
- 某些 web 架構可以在生產模式中以不同的方式部署靜態檔案。
- 在生產模式中執行時，某些 web 架構可能會使用自訂啟動指令碼。
在偵錯模式中於 App Service 內執行應用程式。例如，在 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 路徑，App Service 會使用該路徑來檢查容器是否可以處理要求。 404 回應只是指出路徑不存在，但其可讓 App Service 知道容器狀況良好，並已準備好回應要求。

下一步

教學課程：使用 MySQL 的 PHP 應用程式

App Service Linux 常見問題集

或者，請參閱其他資源：

環境變數和應用程式設定參考