如何在 ServBay 使用 .user.ini 檔案：本地 PHP 設定指南

ServBay 是一套功能強大的整合型本機 Web 開發環境，為開發者量身打造，支援多種語言與技術堆疊，包括靈活的 PHP 版本管理以及便捷的設定調整功能。在實際開發過程中，不同專案常會有不同的 PHP 設定需求，例如檔案上傳大小、記憶體限制或錯誤報告等。如果直接修改全域 php.ini，將會影響到所有專案，這在同時管理多個專案時極為不便。

所幸，PHP 提供了 .user.ini 機制，允許開發者在特定目錄及其子目錄下自訂 PHP 參數，而無需更動全域 php.ini。ServBay 完全支援 .user.ini，讓您能為單一專案或目錄微調 PHP 設定，簡單又高效。

本文將詳盡介紹 .user.ini 的運作原理、在 ServBay 下的使用方式，並透過範例示範如何為特定專案設置自訂 PHP 配置。

.user.ini 檔案簡介

.user.ini 功能自 PHP 5.3.0 引入，作為比舊有 php_value 及 php_flag（如 Apache .htaccess 中）更靈活、更安全的 PHP 參數設定方式。開發者可以將 .user.ini 放置於 Web 可存取的資料夾中，其中的設定僅對該目錄及其子目錄下的 PHP 腳本有效。

主要特色

1. 區域範圍：.user.ini 裡的設定指令僅對其所在目錄及其子目錄生效，不會影響到 ServBay 全域 php.ini 或其他專案的設定。
2. 高度彈性：開發者可依照每個專案需求，定義獨立的 PHP 設定組。
3. 便利管理：無需動用全域伺服器或 PHP 設定，能降低設定衝突風險，並提升專案設定的獨立性與可攜性。
4. 無需重啟：與修改 php.ini 需重啟 PHP-FPM 或 Web 伺服器不同，.user.ini 的變更通常會依 user_ini.cache_ttl 指令指定的時間間隔自動生效（預設通常為 300 秒，即 5 分鐘）。

可設定的參數指令

並非所有 PHP 指令都能在 .user.ini 中設定。指令能否設於 .user.ini，需看其「可變動模式」（Changeable Modes）。僅有標示為 PHP_INI_USER、PHP_INI_PERDIR 或 PHP_INI_ALL 的指令可設定。

常見可在 .user.ini 設定的指令例項：

• upload_max_filesize
• post_max_size
• memory_limit
• display_errors
• log_errors
• max_execution_time
• session.save_path
• date.timezone

屬於 PHP_INI_SYSTEM 模式的指令（如 extension_dir、zend_extension、disable_functions 等）無法於 .user.ini 設定，只能在主 php.ini 或 Web 伺服器設定檔中調整。

欲查看各指令的可變動模式，請參考 PHP 官方手冊關於 php.ini 指令一覽。

在 ServBay 使用 .user.ini 的步驟

於 ServBay 中運用 .user.ini 檔案方式非常直觀。以下以設定 upload_max_filesize 與 memory_limit 為例：

假設您的網站根目錄在 ServBay 預設路徑 /Applications/ServBay/www/ 下，您要為名為 myproject 的專案設定自訂 PHP 配置，其 Web 根目錄為 /Applications/ServBay/www/myproject/public。

步驟一：確認目標目錄

首先，決定自訂 PHP 設定需生效的目錄。一般來說，會是專案對外公開的 Web 根目錄（如 Laravel、Symfony 專案的 public 資料夾），或需特殊設定的子目錄。

例：/Applications/ServBay/www/myproject/public

步驟二：建立或編輯 .user.ini 檔案

於目標目錄下建立一個名為 .user.ini 的新檔案（若已有則編輯即可）。注意 .user.ini 以點開頭，多數檔案系統預設隱藏，請設定檔案管理器顯示隱藏檔案。

您可透過終端機建立檔案：

cd /Applications/ServBay/www/myproject/public
touch .user.ini

然後用文字編輯器打開 .user.ini，輸入所需 PHP 指令，每行一條。例如：

; 設定最大檔案上傳為 20MB
upload_max_filesize = 20M

; 設定 PHP 腳本記憶體上限為 256MB
memory_limit = 256M

; 開啟錯誤顯示（僅建議開發環境使用）
display_errors = On

儲存並關閉 .user.ini。

步驟三：等待設定生效或強制刷新

.user.ini 設定更新不會立即生效，PHP 會快取這些檔案以提升效能。預設 user_ini.cache_ttl 控制快取有效時間，通常是 300 秒（5 分鐘）。變更將在快取到期後自動載入。

若想立刻看到效果，可嘗試以下方法（實際效果視 ServBay 版本與配置）：

1. 重啟相關 PHP-FPM 程序：於 ServBay 介面找出網站所用的 PHP 版本，停止並重啟對應 PHP-FPM 服務。
2. 重啟 ServBay：為最徹底的作法，但將中斷全部本機服務。
3. 等待快取到期：最推薦，一般非立即需求建議耐心等候。

步驟四：確認 .user.ini 設定是否生效

為驗證 .user.ini 設定成功套用，可建立一個簡單 PHP 檔輸出設定資訊。

在放置 .user.ini 的相同目錄（如 /Applications/ServBay/www/myproject/public）創建名為 info.php 的檔案，內容如下：

<?php
phpinfo();
?>

儲存 info.php。

透過瀏覽器進入 ServBay 網站上對應的 info.php。假如您的專案經 ServBay 綁定網域為 myproject.servbay.demo，而 info.php 位於 public，則網址可能為 https://myproject.servbay.demo/info.php。

在 phpinfo() 頁面中，查找已於 .user.ini 設定的指令（如 upload_max_filesize、memory_limit、display_errors），通常會看到兩欄：Master Value 與 Local Value。

• Master Value 表示全域 php.ini 設定值。
• Local Value 表示目前腳本實際生效的值，可能來自 .user.ini 或 Web 伺服器設定。

若 Local Value 顯示為 .user.ini 中您設定的內容（如 20M, 256M, On），則表示 .user.ini 已正確生效。

重要提醒： 驗證完畢後，請務必刪除或限制存取 info.php，以免洩漏詳細伺服器設定資訊造成安全風險。

補充說明與注意事項

• 檔名及位置：.user.ini 必須精確命名並放在希望生效的目錄下，將影響該資料夾及所有子資料夾。
• 指令模式：再次提醒，只有特定模式的參數可於 .user.ini 設定。若設為 PHP_INI_SYSTEM 模式指令將無效且多半不提示錯誤，請參閱 PHP 官方手冊說明。
• 快取：留意 user_ini.cache_ttl 設定。若需頻繁調整並即時看到變更，可臨時將全域 php.ini 內 user_ini.cache_ttl 設至較小值（例：user_ini.cache_ttl = 5），但生產環境不建議，避免影響效能。全域 php.ini 變更需重啟 PHP-FPM。
• 優先順序：PHP 設定優先序為：核心預設 < php.ini (含外掛載入的 .ini 檔) < Web 伺服器設定 (php_value/php_flag，若使用 Apache/nginx 模組) < .user.ini < 程式內 ini_set()。.user.ini 會覆蓋全域設定，但被 ini_set() 覆蓋。
• 安全性：雖然 .user.ini 只限該目錄有效，建議不要將敏感資訊存於此，且通常不應讓其被直接存取。

常見問題 (FAQ)

Q：我新增了 .user.ini 並設定內容，但似乎沒生效，為什麼？

A：可能原因如下：

1. 檔名或位置錯誤：請確保檔名正確為 .user.ini 並放在正確資料夾。
2. 指令模式不支援：可能設定了不支援 .user.ini 的指令（非 PHP_INI_USER 或 PHP_INI_PERDIR），詳見 PHP 手冊。
3. 快取未過期：請等候 user_ini.cache_ttl 時間到或重啟 PHP-FPM。
4. 語法錯誤：檢查 .user.ini 是否有錯字或遺漏。
5. 優先權被覆蓋：程式若用 ini_set() 覆蓋會導致無效。

Q：.user.ini 和全域 php.ini 有什麼不同？

A：全域 php.ini 影響整個 PHP 環境（或該 PHP 版本所有應用），設定值對所有 PHP 腳本生效（除非被較高優先序設定覆蓋）。.user.ini 僅影響其所在及子目錄腳本，且限制於特定模式。其優勢在於可於專案層局部調校且不會動到全域配置。

總結

在 ServBay 利用 .user.ini 檔案是管理專案特定 PHP 配置的推薦方式。其彈性極高，可讓開發者於不影響其他專案或全域 ServBay 設定下，輕鬆調整 PHP 環境以滿足個別需求。經本指南與範例步驟，相信您能熟練操作 .user.ini，有效提升開發效率與環境管理便利。ServBay 的設計宗旨即在賦予開發者強大且靈活的本機開發工具，而完善支援 .user.ini，正是這一理念的最佳實踐。