在 Ubuntu 上安裝 PHP 8.1 並設置本地開發環境

本教程的先前版本由 alenaholligan 撰寫。

介紹

PHP 是一種流行的開源伺服器端腳本語言，專為網頁開發而設計，支撐了互聯網的大量內容，從部落格和電子商務網站到大型應用程式。每次新版本釋出時，PHP 都會提供更佳的效能、安全性及現代開發功能，幫助開發者構建穩健且可擴展的軟體。

PHP 8.1 是一個穩定且具有長期支援的版本，帶來顯著的改進和新的語言功能，同時保持其可靠性。在 Ubuntu 上安裝 PHP 8.1 可以確保您的本地開發環境是最新的、安全的，並且與廣泛使用的框架和平台（如 WordPress、Laravel 以及自訂 PHP 應用程式）相容。

本教程將指導你在 Ubuntu 上安裝 PHP 8.1，並用 Apache 或 Nginx 進行配置，設置必要的 PHP 擴展，並安裝 Composer 以管理依賴。此外，你還將學習如何驗證安裝並排解常見問題。

重點摘要

• 在 Ubuntu 22.04 上安裝 PHP 8.1：Ubuntu 22.04 LTS 在其預設的軟體庫中包含 PHP 8.1，讓你可以使用 apt 安裝穩定且長期支援的 PHP 版本，而不需要第三方 PPA。這確保了可預測的更新、安全修補，以及與現代 PHP 框架的相容性。

• 真實專案所需的 PHP 擴充套件： 大多數生產等級的 PHP 應用程式依賴像是 mysql、curl、xml、mbstring、zip、gd 和 bcmath 等擴充套件。及早安裝這些套件可以避免之後的運行時錯誤，並確保與 Laravel、Symfony 和 WordPress 等框架的相容性。

• 選擇 Apache 或 Nginx 進行 PHP 開發：Apache 可以使用 mod_php 直接執行 PHP，而 Nginx 則需要 PHP‑FPM 來處理請求。這兩種方法在本地開發中都運作良好，但 PHP‑FPM 更接近現代生產環境，並且在負載下的擴展性更好。

• Composer 作為現代 PHP 工作流程的基礎：Composer 透過 composer.json 和 composer.lock 管理專案依賴，確保跨不同機器的一致構建。在安裝框架、生成自動加載器以及在協作 PHP 專案中維護可靠的依賴版本時，它是不可或缺的。

• 專為開發配置 PHP：開發環境受益於詳細的錯誤報告、更高的記憶體限制以及更長的執行時間。在 php.ini 中調整這些設定有助於在開發期間快速發現錯誤，但在生產部署時必須始終恢復這些設定。

• 故障排除和驗證是設置的一部分：使用 php -v 驗證 PHP、檢查已載入的擴展，以及查看 Apache、Nginx 或 PHP‑FPM 日誌都是關鍵步驟。大多數設置問題源於缺少擴展、權限問題或錯誤配置的網頁伺服器指令。

先決條件

要完成本教程，您需要：

• 一台本地機器或運行 Ubuntu 的虛擬伺服器（兼容 Ubuntu 22.04 LTS 及更新版本）
• 對此機器的管理（sudo）存取權
• 活躍的網路連線
• 對指令列有基本了解

如果您正在設置新的 Ubuntu 伺服器，請參閱我們關於 Ubuntu 初始伺服器設置的指南。

步驟 1 — 設定 PHP 8.1

你將在命令列上完成安裝和設定，這是一種非圖形化的方式來與電腦互動。也就是說，你不是點擊按鈕，而是透過鍵入文字來操作，並從電腦那裡以文字方式收到回饋。

命令列，也稱為 shell 或終端機，可以幫助你修改和自動化日常在電腦上執行的許多任務，是軟體開發人員的重要工具。有許多終端機指令可以學習，讓你能夠做更強大的操作。文章《Linux 終端機入門》可以幫助你更好地熟悉終端機。

在 Ubuntu 上，你可以透過點擊螢幕左上角的 Ubuntu 圖示，然後在搜尋欄中輸入 terminal 來找到終端機應用程式。點擊終端機應用程式的圖示即可開啟它。或者，你也可以同時按下鍵盤上的 CTRL、ALT 和 T 鍵，自動開啟終端機應用程式。

執行以下命令以更新可用套件列表，然後安裝 PHP 8.1：

sudo apt update

sudo apt install --no-install-recommends php8.1

--no-install-recommends 標誌將確保不會安裝像 Apache 網頁伺服器這類的其他套件。

使用以下命令檢查您的 PHP 版本資訊：

php -v

你將會收到像這樣的輸出：

PHP 8.1.2-1ubuntu2.22 (cli) (built: Jul 15 2025 12:11:22) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.2-1ubuntu2.22, Copyright (c), by Zend Technologies

這個設定是在 Ubuntu 22.04 LTS 上使用官方 Ubuntu 軟體庫中的 PHP 8.1 套件進行測試的。

安裝網頁開發所需的基本 PHP 擴充功能：

sudo apt install -y php8.1-cli php8.1-common php8.1-mysql php8.1-zip php8.1-gd php8.1-mbstring php8.1-curl php8.1-xml php8.1-bcmath

此命令將安裝以下模組：

• php8.1-cli - 命令直譯器，可用於從 shell 測試 PHP 腳本或執行一般的 shell 腳本任務
• php8.1-common - PHP 的文件、範例和常用模組
• php8.1-mysql - 用於操作 MySQL 資料庫
• php8.1-zip - 用於處理壓縮檔案
• php8.1-gd - 用於處理圖像
• php8.1-mbstring - 用於處理非 ASCII 字串
• php8.1-curl - 讓你在 PHP 中進行 HTTP 請求
• php8.1-xml - 用於處理 XML 資料
• php8.1-bcmath - 用於處理高精度浮點數

PHP 配置文件存放在 /etc/php/8.1/。主要的配置文件是 php.ini，它可能根據您的設定位於不同的目錄中：

• CLI 配置：/etc/php/8.1/cli/php.ini
• Apache 配置：/etc/php/8.1/apache2/php.ini（如果已安裝 Apache）
• PHP-FPM 配置：/etc/php/8.1/fpm/php.ini（如果已安裝 PHP-FPM）

驗證已安裝的擴充功能：

php -m

這列出了所有已載入的 PHP 模組。如果 php -v 顯示的版本與預期不同，可能是因為安裝了多個 PHP 版本。使用 php8.1 -v 可以專門確認 PHP 8.1。

您已安裝 PHP 並確認正在運行的版本。您也安裝了所有需要的 PHP 模組，並能夠列出已加載的模組。

步驟 2 — 使用 Apache 配置 PHP

安裝 Apache PHP 模組：

sudo apt install libapache2-mod-php8.1

啟用模組並重新啟動 Apache：

sudo a2enmod php8.1
sudo systemctl restart apache2

了解 mod_php： mod_php 模組將 PHP 直接嵌入到 Apache 的進程中。當 Apache 收到對 PHP 檔案的請求時，它會使用內嵌的 PHP 直譯器在內部處理這個請求。這與 Nginx 不同，Nginx 需要一個獨立的 PHP-FPM 服務。使用 a2enmod 命令會在 /etc/apache2/mods-enabled/ 中創建符號連結以啟用該模組。

透過在 Apache 的文件根目錄（通常是 /var/www/html）中建立測試檔案來驗證 Apache 是否正確處理 PHP：

echo "<?php phpinfo(); ?>" | sudo tee /var/www/html/info.php

在瀏覽器中訪問 http://localhost/info.php。你應該會看到 PHP 的配置資訊頁面。測試完畢後，為了安全請刪除此文件：

sudo rm /var/www/html/info.php

排解 Apache PHP 問題

如果安裝 mod_php 後 Apache 無法啟動：

檢查 Apache 的錯誤日誌：

sudo tail -20 /var/log/apache2/error.log

常見問題包括：

• 衝突的 PHP 模組：如果您有多個 PHP 版本，請先使用 sudo a2dismod php7.4 停用其他 PHP 模組（如果有的話）
• Apache 配置中的語法錯誤：運行 sudo apache2ctl configtest 來檢查

如果你造訪 localhost 並看到「它運作了！」但 PHP 檔案顯示為純文字：

這意味著 Apache 沒有處理 PHP。請檢查：

1. 確認模組已啟用：

apache2ctl -M | grep php

1. 如果沒有顯示內容，表示模組未載入。請重新啟用它：

sudo a2enmod php8.1
sudo systemctl restart apache2

1. 確認您的 PHP 檔案具有正確的副檔名（.php）並且包含 PHP 程式碼

如果您收到 403 禁止訪問錯誤：

檢查檔案權限：

sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html

Apache 虛擬主機配置

要在本地使用自訂網域進行開發，請建立虛擬主機：

sudo nano /etc/apache2/sites-available/example.local.conf

添加此配置：

<VirtualHost *:80>
    ServerName example.local
    DocumentRoot /var/www/example.local
    <Directory /var/www/example.local>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

• ServerName：此虛擬主機的網域名稱
• DocumentRoot：您的 PHP 檔案所在的位置
• AllowOverride All：允許 .htaccess 檔案覆蓋 Apache 設定（例如 Laravel 這類框架所需）
• Require all granted：允許存取該目錄

建立目錄，啟用網站，並重新啟動 Apache：

sudo mkdir -p /var/www/example.local
sudo chown -R www-data:www-data /var/www/example.local
sudo a2ensite example.local.conf
sudo systemctl restart apache2

將域名添加到您的 /etc/hosts 文件以便本地訪問：

echo "127.0.0.1 example.local" | sudo tee -a /etc/hosts

在 Apache 與 Nginx 之間做選擇

在配置您的網頁伺服器之前，請考慮哪一個最符合您的需求：

何時選擇 Apache：

• 您熟悉 Apache 或需要 .htaccess 支援
• 建立簡單的開發環境
• 使用高度依賴 .htaccess 的框架（某些 WordPress 設置）
• 你偏好較簡單的初始配置

何時選擇 Nginx：

• 你需要在高負載下有更好的性能
• 你想要模仿現代的生產環境
• 你正在構建能夠擴展的應用程式
• 你偏好較現代的建築風格

兩者在本地開發中都同樣有效。選擇通常取決於個人偏好或現有的基礎設施。

步驟 3 — 使用 Nginx 配置 PHP

安裝 PHP-FPM（FastCGI 進程管理器）：

sudo apt install php8.1-fpm

啟動並啟用 PHP-FPM：

sudo systemctl start php8.1-fpm
sudo systemctl enable php8.1-fpm

理解 PHP-FPM 與 FastCGI：與 Apache 的 mod_php 不同，Nginx 並不直接處理 PHP。PHP-FPM（FastCGI 進程管理器）作為一個獨立的服務運行，Nginx 通過 FastCGI 協議與其通信。FastCGI 是一種用於程式與網頁伺服器介面的二進位協議——它比傳統的 CGI 更快，因為它可以在請求之間保持進程持續運行。

當 Nginx 收到對 PHP 文件的請求時，它會通過 Unix 套接字（或 TCP 連接）將請求轉發給 PHP-FPM。PHP-FPM 處理 PHP 代碼並將結果返回給 Nginx，然後 Nginx 將結果發送給客戶端。這種分離允許 PHP-FPM 管理自己的進程池，從而提升性能和資源管理能力。

Nginx 伺服器區塊配置

建立伺服器區塊配置：

sudo nano /etc/nginx/sites-available/example.local

添加此配置：

server {
    listen 80;
    server_name example.local;
    root /var/www/example.local;
    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

設定說明：

• root：存放你的 PHP 檔案的目錄
• location ~ \.php$：使用正則表達式匹配所有以 .php 結尾的請求
• include snippets/fastcgi-php.conf：包含 Nginx 的預設 FastCGI 配置（設定 SCRIPT_FILENAME 及其他所需變數）
• fastcgi_pass unix:/var/run/php/php8.1-fpm.sock：PHP-FPM 監聽的 Unix 套接字。這是 Nginx 與 PHP-FPM 通訊的方式。套接字路徑定義在 /etc/php/8.1/fpm/pool.d/www.conf

啟用網站並測試配置：

sudo mkdir -p /var/www/example.local
sudo chown -R www-data:www-data /var/www/example.local
sudo ln -s /etc/nginx/sites-available/example.local /etc/nginx/sites-enabled/
sudo nginx -t

如果測試通過，重啟 Nginx：

sudo systemctl restart nginx

將網域新增到 /etc/hosts：

echo "127.0.0.1 example.local" | sudo tee -a /etc/hosts

建立一個測試 PHP 檔案：

echo "<?php phpinfo(); ?>" | sudo tee /var/www/example.local/info.php

訪問 http://example.local/info.php。你應該能看到 PHP 的配置頁面。驗證後請刪除測試文件：

sudo rm /var/www/example.local/info.php

排解 Nginx PHP 問題

如果你收到「502 錯誤網關」：

這表示 Nginx 無法與 PHP-FPM 通訊。請檢查：

1. 確認 PHP-FPM 是否正在運行：

sudo systemctl status php8.1-fpm

1. 檢查套接字路徑是否正確。套接字位置定義在 /etc/php/8.1/fpm/pool.d/www.conf:

grep listen /etc/php/8.1/fpm/pool.d/www.conf

你應該會看到類似 listen=/run/php/php8.1-fpm.sock 的內容。你在 Nginx 配置中的路徑必須完全匹配。請注意 /var/run 通常是指向 /run 的符號連結，因此兩個路徑都可以使用。

1. 檢查套接字檔案權限：

ls -la /var/run/php/php8.1-fpm.sock

該套接字應該由 www-data 或 Nginx 運行的使用者擁有。如果權限錯誤：

sudo chown www-data:www-data /var/run/php/php8.1-fpm.sock

1. 檢查 Nginx 錯誤日誌：

sudo tail -20 /var/log/nginx/error.log

你可能會看到如下錯誤：

connect() to unix:/var/run/php/php8.1-fpm.sock failed (2: No such file or directory)

這表示套接字路徑不正確或 PHP-FPM 沒有運行。

如果 PHP 文件被下載而不是執行：

這表示 Nginx 並未將 PHP 檔案傳遞給 PHP-FPM。請檢查：

• 在您的伺服器配置中存在 location ~ \.php$ 區塊
• fastcgi_pass 指令指向正確的 socket
• 在進行更改後，你已重新啟動 Nginx

如果出現「找不到檔案」錯誤：

檢查 snippets/fastcgi-php.conf 是否存在：

ls -la /etc/nginx/snippets/fastcgi-php.conf

這個檔案設定了 SCRIPT_FILENAME，它告訴 PHP-FPM 要執行哪個檔案。沒有它，PHP-FPM 就不知道要處理哪個檔案。

步驟 4 — 為開發環境配置 PHP

透過調整 php.ini 中的錯誤報告、顯示設定和記憶體限制來配置 PHP 以進行開發。這些設定與生產環境的配置不同。

PHP 為 CLI（命令列介面）和網頁伺服器使用分別的設定檔。請編輯相應的檔案：

對於 CLI（當從終端機運行 PHP 時）：

sudo nano /etc/php/8.1/cli/php.ini

適用於網頁伺服器（Apache 或 Nginx 搭配 PHP-FPM）：

# For Apache
sudo nano /etc/php/8.1/apache2/php.ini

# For PHP-FPM (Nginx)
sudo nano /etc/php/8.1/fpm/php.ini

基本開發設定

在您的 php.ini 檔案中找到並更新這些設定：

display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
error_log = /var/log/php_errors.log
memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
date.timezone = America/New_York

每個設定的功能：

• display_errors=On：直接在瀏覽器中顯示 PHP 錯誤（對除錯有幫助，但在生產環境中很危險）
• display_startup_errors=On：顯示 PHP 啟動期間發生的錯誤
• error_reporting=E_ALL：報告所有類型的錯誤（警告、通知等）
• log_errors=On：將錯誤寫入日誌檔案
• error_log：PHP 記錄錯誤的地方
• memory_limit=256M：腳本可以使用的最大記憶體（如果出現“記憶體耗盡”錯誤，請增加此值）
• upload_max_filesize=64M：上傳檔案的最大尺寸
• post_max_size=64M：POST 資料的最大大小（必須大於 upload_max_filesize）
• max_execution_time=300：腳本可執行的最長時間（以秒為單位）
• date.timezone：設定預設時區（使用您當地的時區：Asia/Kolkata、Europe/London、UTC 等）。

在進行更改後，重新啟動您的網頁伺服器：

# For Apache
sudo systemctl restart apache2

# For PHP-FPM
sudo systemctl restart php8.1-fpm

正在驗證您的設定

檢查您的更改是否生效：

# For CLI
php -i | grep display_errors

# For web server (create a test file)
echo "<?php phpinfo(); ?>" | sudo tee /var/www/html/test.php

在瀏覽器中訪問測試文件，並搜尋 display_errors。它應該顯示為 On。驗證後請刪除測試文件。

如果您的更改未顯示：

1. 請確保你編輯了正確的 php.ini 文件（CLI 與網頁伺服器）
2. 檢查設定名稱是否有拼寫錯誤（它們區分大小寫）
3. 在進行更改後重新啟動您的網頁伺服器
4. 某些設定可以被專案目錄中的 .htaccess（Apache）或 php.ini 覆蓋

你可以立即開始使用 PHP，但你可能會希望使用各種函式庫來快速建立 PHP 應用程式。在測試你的 PHP 環境之前，先為你的專案設置一個依賴管理工具。

步驟 5 — 設定 Composer 以管理相依性（可選）

函式庫是一組可以幫助你解決常見問題的程式碼，讓你不需要自己寫所有的程式碼。由於有許多函式庫可供使用，當你在撰寫 PHP 的經驗增加時，使用依賴管理工具將有助於你管理多個函式庫。

Composer 是 PHP 中用於依賴管理的工具。它允許你聲明專案所依賴的函式庫，並會負責安裝和更新這些套件。

雖然類似，但 Composer 並不像 yum 或 apt 那樣的套件管理器。它處理「套件」或函式庫，但它是以每個專案為單位來管理，將它們安裝在專案內的某個目錄（例如 vendor）中。預設情況下，它不會全域安裝任何東西。因此，它是一個依賴管理器。不過，為了方便，Composer 也支援透過 global 指令管理全域專案。

這個想法並不新穎，Composer 深受 Node 的 npm 和 Ruby 的 bundler 啟發。

假設：

• 你有一個依賴多個程式庫的專案。
• 其中一些程式庫依賴於其他程式庫。

作曲者：

• 讓您可以宣告您所依賴的函式庫。
• 找出可以安裝和需要安裝的套件版本，並將它們下載到你的專案中進行安裝。
• 讓您可以透過一個指令更新所有依賴項。
• 讓您可以參閱「基本使用」章節，以了解有關宣告依賴的更多詳細資訊。

下載 Composer 安裝程式：

curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php

透過檢查安裝程式的 SHA-384 雜湊值來驗證其完整性。取得最新的雜湊值：

HASH=$(curl -sS https://composer.github.io/installer.sig)

驗證哈希是否匹配：

php -r "if (hash_file('SHA384', '/tmp/composer-setup.php') === '$HASH') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('/tmp/composer-setup.php'); } echo PHP_EOL;"

你應該看看：

Installer verified

如果你看到 Installer corrupt，表示下載不完整或已被篡改。請重新下載安裝程式並驗證雜湊值。如果仍然失敗，請檢查你的網路連接或嘗試從不同的網路下載。

全域安裝 Composer：

sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer

你將會收到類似這樣的輸出內容：

All settings correct for using Composer
Downloading...

Composer (version 2.3.5) successfully installed to: /usr/local/bin/composer
Use it: php /usr/local/bin/composer

測試你的安裝：

composer

你將會收到如下的輸出：

   ______
  / ____/___  ____ ___  ____  ____  ________  _____
 / /   / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/
/ /___/ /_/ / / / / / / /_/ / /_/ (__  )  __/ /
\____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
                    /_/
Composer version 2.3.5 2022-04-13 16:43:00

Usage:
  command [options] [arguments]

Options:
  -h, --help                     Display help for the given command. When no command is given display help for the list command
  -q, --quiet                    Do not output any message
  -V, --version                  Display this application version
      --ansi|--no-ansi           Force (or disable --no-ansi) ANSI output
  -n, --no-interaction           Do not ask any interactive question
      --profile                  Display timing and memory usage information
      --no-plugins               Whether to disable plugins.
      --no-scripts               Skips the execution of all scripts defined in composer.json file.
  -d, --working-dir=WORKING-DIR  If specified, use the given directory as working directory.
      --no-cache                 Prevent use of the cache
  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
. . .

這確認了 Composer 已成功安裝在您的系統上，並且在整個系統中可用。

步驟 6 — 在 PHP 專案中使用 Composer

作為最後一步，您可以選擇使用 composer init 初始化您的專案。這將建立 composer.json 檔案，用來管理您的專案依賴。初始化專案也讓您可以定義專案的詳細資訊，例如作者和授權，並使用 Composer 的自動載入功能。您現在可以定義依賴，也可以稍後再新增。

建立專案目錄並初始化 Composer：

cd ~
mkdir example-project
cd example-project
composer init

執行此指令將啟動設定精靈。在精靈中輸入的詳細資訊以後可以更新，因此可以保留預設值，直接按 ENTER 即可。如果你尚未準備好安裝任何依賴項，可以選擇 no。在每個提示中輸入你的詳細資訊：

                                            
  Welcome to the Composer config generator  
                                            


This command will guide you through creating your composer.json config.

Package name (<vendor>/<name>) [sammy/example-project]:  sammy/project1
Description []:
Author [n to skip]: Sammy <sammy@linux-console.net>
Minimum Stability []: 
Package Type (e.g. library, project, metapackage, composer-plugin) []: project
License []: 

Define your dependencies.

Would you like to define your dependencies (require) interactively [yes]? no
Would you like to define your dev dependencies (require-dev) interactively [yes]? no

Add PSR-4 autoload mapping? Maps namespace "Sammy\Project1" to the entered relative path. [src/, n to skip]: n

{
    "name": "sammy/project1",
    "type": "project",
    "authors": [
        {
            "name": "Sammy",
            "email": "sammy@linux-console.net"
        }
    ],
    "require": {}
}

Do you confirm generation [yes]? yes

在您確認生成之前，您將會看到嚮導將創建的 composer.json 文件示例。如果一切看起來都沒問題，您可以確認默認的 是。如果您需要重新開始，請選擇 否。

當你第一次定義任何依賴時，Composer 會創建一個 vendor 資料夾。所有依賴都會安裝到這個 vendor 資料夾中。Composer 還會創建一個 composer.lock 檔案。該檔案指定了專案中每個依賴和子依賴使用的 精確 版本。這可以確保在任何運行你的程式的機器上，都使用相同版本的每個套件。

現在你已經安裝了 PHP，並且有使用 Composer 管理專案依賴的方法，你已經可以準備測試你的環境了。

第七步 — 測試 PHP 環境

建立並執行一個基本的 PHP 腳本來測試您的安裝：

nano hello.php

加入以下 PHP 代碼：

<?php
echo 'Hello World!';
?>

保存並關閉檔案（按 CTRL+X，然後按 Y，再按 ENTER）。執行腳本：

php hello.php

如果 PHP 被正確處理，你將只看到引號內的字符：

Hello World!

PHP 已成功處理該腳本，這意味著您的 PHP 環境已成功安裝，並且您已準備好繼續您的程式設計旅程。

第八步 — 建立實際的 PHP 專案

現代的 PHP 框架如 Laravel、Symfony 和 WordPress 需要特定的 PHP 擴展和 Composer。使用 Composer 或框架的安裝程序安裝框架，然後配置您的網頁伺服器指向專案的 public 目錄。

設定 Laravel

使用 Composer 安裝 Laravel：

composer create-project laravel/laravel my-laravel-app
cd my-laravel-app

此指令會下載 Laravel 及其所有依賴項。此過程可能需要幾分鐘。

Laravel 需要這些 PHP 擴展（已在步驟 1 安裝）：

• php8.1-mbstring - 多字節字串處理
• php8.1-xml - XML 解析
• php8.1-curl - HTTP 請求
• php8.1-zip - 檔案壓縮處理
• php8.1-bcmath - 任意精度數學

如果 Laravel 提示「缺少 mbstring」，即使你已經安裝了它：

這通常表示擴充功能已安裝但未載入。請檢查：

1. 確認已安裝擴充功能：

php -m | grep mbstring

1. 如果缺少，請安裝它：

sudo apt install php8.1-mbstring

1. 如果已安裝但未顯示，請重新啟動您的網頁伺服器：

# For Apache
sudo systemctl restart apache2

# For PHP-FPM
sudo systemctl restart php8.1-fpm

1. 檢查正在使用哪個 php.ini 文件。Laravel 的安裝程式使用 CLI PHP，因此請檢查：

php --ini

確保在 CLI 的 php.ini 檔案中啟用了該擴展。

驗證 Laravel 安裝：

安裝完成後，啟動 Laravel 的開發伺服器：

php artisan serve

你應該看看：

INFO  Server running on [http://127.0.0.1:8000]

在你的瀏覽器中訪問 http://localhost:8000。你應該會看到 Laravel 的歡迎頁面。

適用於類似正式環境的 Apache 或 Nginx 設定：

將您的網頁伺服器設定為指向 public 目錄（不是專案根目錄）。Laravel 的 public/index.php 是所有請求的進入點。

設定 WordPress

下載並解壓縮 WordPress：

cd /var/www
sudo wget https://wordpress.org/latest.tar.gz
sudo tar -xzf latest.tar.gz
sudo chown -R www-data:www-data /var/www/wordpress

WordPress 需要 MySQL 或 MariaDB 資料庫。如有需要，請安裝 MySQL：

sudo apt install mysql-server
sudo mysql_secure_installation

mysql_secure_installation 腳本將提示您執行以下操作：

• 設定 root 密碼
• 移除匿名使用者
• 禁止遠端以 root 登入
• 刪除測試資料庫
• 重新載入權限表

為 WordPress 建立資料庫和使用者：

sudo mysql -u root -p

在 MySQL 提示符中：

CREATE DATABASE wordpress_db;
CREATE USER 'wpuser'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON wordpress_db.* TO 'wpuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

將 secure_password 替換為一個強密碼。WordPress 將使用這些憑證來連接資料庫。

如果 WordPress 無法連接到資料庫：

1. 確認 MySQL 是否正在運行：

sudo systemctl status mysql

1. 測試資料庫連線：

mysql -u wpuser -p wordpress_db

如果這失敗，請檢查：

• 用戶名和密碼正確
• 資料庫已存在：SHOW DATABASES;
• 使用者擁有的權限：SHOW GRANTS FOR 'wpuser'@'localhost';

1. 檢查是否已安裝 PHP 的 MySQL 擴展：

php -m | grep mysql

如果沒有，請安裝它：

sudo apt install php8.1-mysql
sudo systemctl restart apache2  # or php8.1-fpm for Nginx

完成 WordPress 安裝：

將您的網頁伺服器配置指向 /var/www/wordpress（Apache 請參見步驟 2，Nginx 請參見步驟 3）。在瀏覽器中訪問該網站。WordPress 會提示您：

1. 選擇你的語言
2. 輸入資料庫憑證（使用您建立的資料庫名稱、使用者名稱和密碼）
3. 完成安裝

設定 Symfony

使用 Composer 安裝 Symfony：

composer create-project symfony/website-skeleton my-symfony-app
cd my-symfony-app

Symfony 需要與 Laravel 相同的擴展。啟動開發伺服器：

symfony server:start

或者使用 PHP 內建的伺服器：

php -S localhost:8000 -t public

如果 Symfony 安裝因擴展錯誤而失敗：

檢查所有必要的擴充套件是否已安裝並載入：

php -m | grep -E 'mbstring|xml|curl|zip|bcmath'

如果有任何遺失，請安裝它們並重新啟動您的網頁伺服器。

步驟 9 — 本地開發的最佳實踐

保護您的本地環境，使用版本控制，配置正確的檔案權限，並設置環境特定的配置。這些做法可以防止安全問題，並使開發過程更順暢。

安全考量

即使在本地開發中，也要遵循安全最佳實踐：

1. 在生產環境中禁用危險的 PHP 函數：像 exec()、system() 和 shell_exec() 這類函數應該在生產環境的 php.ini 文件中被限制使用。

2. 使用環境變數：將敏感配置存儲在 .env 文件中（切勿將其提交到版本控制）。Laravel 和 Symfony 原生支持這種做法。

3. 設定適當的檔案權限：網頁伺服器檔案應該可供網頁伺服器使用者讀取，但不可寫入：

sudo chown -R www-data:www-data /var/www/your-project
sudo find /var/www/your-project -type d -exec chmod 755 {} \;
sudo find /var/www/your-project -type f -exec chmod 644 {} \;

為什麼這些權限很重要：目錄需要 755（擁有者可讀、寫、執行；其他人可讀和執行），以便網頁伺服器可以瀏覽它們。檔案需要 644（擁有者可讀和寫；其他人只能讀取），以便網頁伺服器可以讀取但無法修改它們。這可以防止惡意腳本覆蓋您的檔案。

版本控制整合

對你的 PHP 專案始終使用版本控制。在專案目錄中初始化 Git：

cd /var/www/your-project
git init

建立一個 .gitignore 檔案來排除不必要的檔案：

/vendor/
/node_modules/
.env
.DS_Store
*.log

效能優化

為了在本地開發中獲得更好的性能：

• 啟用 OPcache：OPcache 隨 PHP 8.1 一起提供，通過緩存已編譯的 PHP 代碼來提升性能。

• 使用 Composer 的自動加載器優化：

composer install --optimize-autoloader --no-dev

• 配置 PHP-FPM 池 以便在使用 Nginx 時更好地管理資源。

第10步 — 疑難排解常見問題

常見的 PHP 安裝問題包括缺少擴展、檔案權限設定錯誤、網頁伺服器配置錯誤以及版本衝突。大多數問題可以透過檢查擴展安裝、驗證檔案權限和檢視網頁伺服器日誌來解決。

PHP 擴展未加載

如果 php -m 沒有顯示你剛安裝的擴展：

• 確認它是否已安裝：

dpkg -l | grep php8.1-extension_name

• 檢查擴展檔案是否存在：

ls /usr/lib/php/*/extension_name.so

• 請確認在 php.ini 中已啟用。有些擴充套件需要明確啟用：

grep -i extension_name /etc/php/8.1/*/php.ini

• 重新啟動您的網頁伺服器：

# For Apache
sudo systemctl restart apache2

# For PHP-FPM
sudo systemctl restart php8.1-fpm

• 檢查正在使用的 php.ini 檔案：

php --ini

請確保你正在檢查正確的 php.ini 文件（命令列界面 vs 網頁伺服器）。

如果擴充功能仍未出現：

• 某些擴充功能需要額外的系統函式庫。請查看擴充功能的文件說明
• 請確認你安裝了正確的版本（php8.1-extension，而不是 php8.0-extension）
• 檢查可能干擾的衝突 PHP 版本

500 內部伺服器錯誤

500 錯誤表示伺服器遇到錯誤，但無法顯示詳細資訊。請檢查錯誤日誌：

# Apache
sudo tail -20 /var/log/apache2/error.log

# Nginx
sudo tail -20 /var/log/nginx/error.log

# PHP-FPM
sudo tail -20 /var/log/php8.1-fpm.log

常見原因與解決方法：

1. 檔案權限錯誤：PHP 檔案必須可被網頁伺服器使用者讀取

sudo chown -R www-data:www-data /var/www/your-project
sudo find /var/www/your-project -type f -exec chmod 644 {} \;
sudo find /var/www/your-project -type d -exec chmod 755 {} \;

1. 缺少 PHP 擴展：檢查錯誤日誌中是否有類似“調用未定義函數”的訊息。安裝缺少的擴展並重新啟動網絡伺服器。

2. PHP 檔案中的語法錯誤：錯誤日誌會顯示檔案名稱及行號。常見問題：

   • 缺少分號
   • 未閉合的括號或引號
   • 使用未定義的函數或類

3. 網絡伺服器配置錯誤：

   • Apache：檢查虛擬主機配置、模組載入
   • Nginx：驗證 PHP-FPM 套接字路徑、FastCGI 配置

4. PHP 記憶體限制超過：如果您看到「已耗盡允許的記憶體大小」錯誤，請在 php.ini 中增加 memory_limit

PHP 版本衝突

如果 php -v 顯示的版本與預期不同，表示你安裝了多個 PHP 版本。

檢查已安裝的版本：

dpkg -l | grep php | grep -E 'php[0-9]'

明確使用正確的版本：

php8.1 -v
php8.1 -m

將您的網頁伺服器更新至 PHP 8.1：

對於 Apache，請停用其他 PHP 模組並啟用 PHP 8.1：

sudo a2dismod php7.4 php8.0  # if they exist
sudo a2enmod php8.1
sudo systemctl restart apache2

對於 PHP-FPM，停止其他版本並啟動 PHP 8.1：

sudo systemctl stop php7.4-fpm php8.0-fpm  # if they exist
sudo systemctl start php8.1-fpm
sudo systemctl enable php8.1-fpm

將 PHP 8.1 設為預設 CLI 版本：

sudo update-alternatives --set php /usr/bin/php8.1

作曲家記憶問題

如果 Composer 記憶體不足，你會看到類似的錯誤：

Fatal error: Allowed memory size of 134217728 bytes exhausted

透過增加記憶體來執行 Composer 修復它：

php -d memory_limit=512M /usr/local/bin/composer install

或在 php.ini 中增加 PHP 的記憶體限制：

memory_limit = 512M

如果 Composer 安裝因哈希不匹配而失敗：

如果出現以下情況，哈希驗證可能會失敗：

• 自您下載安裝程式以來，它已經更新過（請重新下載以獲取最新的驗證碼）
• 您的下載檔案已損壞（請重試下載）
• 你正在使用會修改檔案的代理伺服器（請檢查你的網路設定）

資料庫連線問題

如果您的 PHP 應用無法連接到 MySQL/MariaDB，您可能會看到類似以下的錯誤：

SQLSTATE[HY000] [2002] No such file or directory

或

Access denied for user 'username'@'localhost'

疑難排解步驟：

1. 確認資料庫服務正在運行：

sudo systemctl status mysql

如果它沒有運行，請啟動它：

sudo systemctl start mysql
sudo systemctl enable mysql

1. 檢查是否已安裝 PHP 的 MySQL 擴展：

php -m | grep mysql

如果沒有安裝，請安裝它：

sudo apt install php8.1-mysql
sudo systemctl restart apache2  # or php8.1-fpm for Nginx

1. 驗證資料庫憑證和權限。測試連線：

mysql -u username -p database_name

如果這失敗，請檢查：

• 用戶名和密碼正確
• 資料庫已存在：SHOW DATABASES;
• 使用者擁有的權限：SHOW GRANTS FOR 'username'@'localhost';

PHP 檔案顯示為純文字而未執行

如果你的 PHP 檔案在瀏覽器中顯示為純文字：

1. 檢查檔案副檔名：它必須是 .php，而不是 .txt 或 .html

2. 驗證 PHP 是否正在處理檔案：

   • Apache：檢查 mod_php 是否已啟用：apache2ctl -M | grep php
   • Nginx：檢查 PHP-FPM 是否正在運行以及 socket 路徑是否正確

3. 檢查檔案權限：網頁伺服器必須能夠讀取該檔案

4. 驗證檔案是否包含 PHP 代碼：確保它以 <?php 或 <? 開頭

5. 檢查網頁伺服器配置：

   • Apache：虛擬主機可能未正確配置
   • Nginx：location ~ \.php$ 區塊可能缺失或不正確

檔案上傳問題

如果檔案上傳失敗，您可能會看到類似以下的錯誤：

The uploaded file exceeds the upload_max_filesize directive

檢查這些 php.ini 設定：

upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300

重要： post_max_size 必須大於 upload_max_filesize。如果您設置 upload_max_filesize=100M，請將 post_max_size=110M 或更高。

如果上傳仍然失敗：

1. 查看錯誤日誌以獲取具體的錯誤訊息
2. 確認上傳目錄存在且可寫入：

sudo chmod 755 /path/to/upload/directory
sudo chown www-data:www-data /path/to/upload/directory

1. 檢查磁碟空間：df -h
2. 確認表單使用 enctype="multipart/form-data"

在修改 php.ini 後，請重新啟動您的網頁伺服器。

常見問題

我該如何在 Ubuntu 上安裝 PHP 8.1？

使用 Ubuntu 的套件管理器安裝 PHP 8.1：sudo apt update && sudo apt install php8.1。PHP 8.1 已包含在 Ubuntu 的預設軟體庫中，因此不需要其他套件來源。

哪些 PHP 擴展對開發是必需的？

必要的擴展包括 php8.1-cli、php8.1-mysql、php8.1-curl、php8.1-xml、php8.1-mbstring、php8.1-zip、php8.1-gd 以及 php8.1-bcmath。這些擴展涵蓋了資料庫連接、HTTP 請求、字串處理及影像處理。

我該如何配置 PHP 與 Apache 或 Nginx？

對於 Apache，安裝 libapache2-mod-php8.1 並使用 sudo a2enmod php8.1 啟用它。對於 Nginx，安裝 php8.1-fpm，並配置 Nginx 將 PHP 請求通過 FastCGI 傳送到 PHP-FPM 套接字。

我如何確認 PHP 是否正確安裝？

執行 php -v 來檢查 PHP 版本。建立一個測試檔案，內容為 <?php phpinfo(); ?>，然後透過你的網頁伺服器存取它，以查看詳細的 PHP 配置信息。

我可以用這個設置在本地運行 Laravel 或 WordPress 嗎？

是的。Laravel 需要 Composer 和上述提到的標準 PHP 擴展。WordPress 除了 PHP 外還需要一個 MySQL 資料庫。這兩個框架都可以搭配 Apache 或 Nginx 配置使用。

我該如何為 PHP 專案安裝 Composer？

下載 Composer 安裝程式，驗證其雜湊值，然後全域安裝：sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer。使用 composer --version 驗證。

我該如何排除 PHP 擴展缺失的問題？

使用 php -m 檢查已安裝的擴充功能。使用 sudo apt install php8.1-extension_name 安裝缺少的擴充功能，然後重新啟動您的網頁伺服器。

我該如何為開發環境設定 PHP 錯誤報告？

編輯 php.ini 並設定 display_errors=On、error_reporting=E_ALL 和 log_errors=On。請記得在生產環境中關閉錯誤顯示。

Apache 和 Nginx 在 PHP 上有什麼不同？

Apache 使用 mod_php 直接處理 PHP（PHP 嵌入在 Apache 的進程中），而 Nginx 則需要 PHP-FPM（FastCGI Process Manager）來處理 PHP 請求（PHP 作為獨立服務運行）。詳情請見上方的「Apache 與 Nginx 的選擇」部分的比較表。兩種方式都能運作良好；選擇時可根據性能需求、熟悉程度及現有基礎設施來決定。

我可以在同一系統上安裝多個 PHP 版本嗎？

是的，可以使用像 phpenv 或 phpbrew 這樣的工具。不過，對於大多數開發情境來說，使用單一 PHP 版本就已經足夠。當你需要測試應用程式對不同 PHP 版本的相容性時，再使用版本管理工具。

結論

您現在已經在 Ubuntu 上擁有一個完全配置的 PHP 8.1 開發環境，支持 Apache 和 Nginx 網頁伺服器。您的設置包括必要的 PHP 擴展、用於依賴管理的 Composer，以及適合本地開發的正確配置。

在開始下一個專案之前，考慮設置一個整合開發環境（IDE），例如安裝了 PHP 擴充功能的 VS Code，以獲得語法高亮、除錯和智能感知支援。

當你的開發環境準備就緒後，你可以進一步探索 PHP 開發：

• 透過《如何在 PHP 中處理字串》學習 PHP 基礎
• 使用《如何在 PHP 中使用 Web API》來建立 API
• 了解《如何在 PHP 中使用函數》中的函數
• 在 Ubuntu 上安裝和使用 PostgreSQL 的資料庫設置方法

對於生產環境部署，建議使用 Linux-Console.net 應用平台，直接從 GitHub 部署您的 PHP 應用，並自動進行擴展和 SSL 證書管理。

感謝您與 Linux-Console.net 社群一起學習。