配置管理是應用可移植性、安全性、環境隔離的基石。本文系統對比 INI 檔案、PHP 陣列、YAML、環境變數、Consul/Etcd 分散式配置** 五大方案,提供從單體應用到微服務的演進路徑與代碼實戰。
| 方案 | 優點 | 缺點 | 適用階段 |
|---|---|---|---|
| php.ini / .user.ini | PHP 內建、效能最好 (OPcache 直接快取) | 唯讀、全域共享、難以版控、敏感資訊洩露風險 | PHP 執行時參數調優 (memory_limit, max_execution_time) |
PHP 陣列回傳 (config.php) | 原生語法、IDE 支援完美、可邏輯運算、快取友善 | 敏感資訊明文、需防止 Web 訪問、多環境切換麻煩 | 中小型專案、單體應用 |
INI 檔案 (parse_ini_file) | 標準格式、非技術人員可編輯、支援區段 | 型別轉換弱、無巢狀結構、解析較慢 | 舊系統遷移、簡單配置 |
YAML (symfony/yaml) | 人類可讀、支援巢狀、錨點別名、型別豐富 | 需額外依賴、解析慢、YAML 陷阱多 (隱性類型轉換) | Symfony/Laravel 專案、複雜結構配置 |
| 環境變數 ( Twelve-Factor App ) | 環境隔離絕對、敏感資訊不入代碼庫、容器/K8s 原生支援、CI/CD 友善 | 型別皆為字串、無結構、需前置解析層 | 所有生產環境、雲原生應用 |
| 分散式配置中心 (Consul, Etcd, Nacos, Apollo) | 動態更新無需重啟、集中管理、版本控制、審計追蹤 | 架構複雜、引入外部依賴、網路延遲 | 微服務、多叢集、多團隊協作 |
採用 「環境變數作為單一真實來源」+「PHP 配置類解析驗證」 模式:
# .env (加入 .gitignore,生產環境由平台注入)
APP_ENV=local
APP_DEBUG=true
APP_URL=https://localhost
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=myapp
DB_USERNAME=dev_user
DB_PASSWORD=dev_pass
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="noreply@example.com"
MAIL_FROM_NAME="${APP_NAME}"
vlucas/phpdotenv)composer require vlucas/phpdotenv
<?php
// bootstrap/config.php
use Dotenv\Dotenv;
$dotenv = Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();
// $dotenv->required(['DB_HOST', 'DB_DATABASE'])->notEmpty(); // 驗證必要變數
return [
'app' => [
'env' => env('APP_ENV', 'production'),
'debug' => filter_var(env('APP_DEBUG', false), FILTER_VALIDATE_BOOLEAN),
'url' => env('APP_URL'),
'timezone' => 'Asia/Taipei',
'locale' => 'zh_TW',
],
'database' => [
'default' => env('DB_CONNECTION', 'mysql'),
'connections' => [
'mysql' => [
'driver' => 'mysql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => (int) env('DB_PORT', 3306),
'database' => env('DB_DATABASE'),
'username' => env('DB_USERNAME'),
'password' => env('DB_PASSWORD'),
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
'prefix' => '',
'strict' => true,
'engine' => 'InnoDB',
'options' => [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::ATTR_EMULATE_PREPARES => false,
],
],
],
],
'redis' => [
'client' => env('REDIS_CLIENT', 'phpredis'),
'default' => [
'host' => env('REDIS_HOST', '127.0.0.1'),
'password' => env('REDIS_PASSWORD'),
'port' => (int) env('REDIS_PORT', 6379),
'database' => (int) env('REDIS_DB', 0),
],
],
// ... 其他服務配置
];
// 輔助函式
function env(string $key, mixed $default = null): mixed {
$value = $_ENV[$key] ?? $_SERVER[$key] ?? getenv($key);
if ($value === false) return $default;
// 型別轉換
switch (strtolower($value)) {
case 'true': return true;
case 'false': return false;
case 'null': return null;
case 'empty': return '';
}
// 數值轉換
if (is_numeric($value)) {
return str_contains($value, '.') ? (float)$value : (int)$value;
}
return $value;
}
<?php
namespace App\Config;
readonly class DatabaseConfig {
public function __construct(
public string $driver,
public string $host,
public int $port,
public string $database,
public string $username,
public string $password,
public string $charset = 'utf8mb4',
public array $options = [],
) {}
public function dsn(): string {
return "{$this->driver}:host={$this->host};port={$this->port};dbname={$this->database};charset={$this->charset}";
}
}
// 建構器
class ConfigFactory {
public static function createDatabaseConfig(array $config): DatabaseConfig {
return new DatabaseConfig(
driver: $config['driver'],
host: $config['host'],
port: $config['port'],
database: $config['database'],
username: $config['username'],
password: $config['password'],
charset: $config['charset'] ?? 'utf8mb4',
options: $config['options'] ?? [],
);
}
}
<?php
// 使用 Symfony Config + Cache 組件實現熱更新
use Symfony\Component\Config\FileLocator;
use Symfony\Component\Config\Loader\DelegatingLoader;
use Symfony\Component\Config\Loader\LoaderResolver;
use Symfony\Component\Config\Resource\FileResource;
use Symfony\Component\Yaml\YamlFileLoader;
$locator = new FileLocator([__DIR__ . '/../config']);
$resolver = new LoaderResolver([new YamlFileLoader($locator)]);
$loader = new DelegatingLoader($resolver);
$configValues = $loader->load('services.yaml', 'yaml');
// 配合 Cache 組件實現變更檢測自動重載
<?php
// 簡易 Consul 配置客戶端
class ConsulConfig {
private \GuzzleHttp\Client $http;
private string $datacenter;
private string $token;
private array $cache = [];
public function __construct(string $host = '127.0.0.1', int $port = 8500, string $token = '') {
$this->http = new \GuzzleHttp\Client(['base_uri' => "https://{$host}:{$port}/v1/"]);
$this->token = $token;
}
public function get(string $key, mixed $default = null): mixed {
if (isset($this->cache[$key])) return $this->cache[$key];
try {
$response = $this->http->get("kv/{$key}", [
'headers' => $this->token ? ['X-Consul-Token' => $this->token] : [],
'query' => ['raw' => 'true']
]);
$value = $response->getBody()->getContents();
$this->cache[$key] = $value === '' ? $default : json_decode($value, true) ?? $value;
return $this->cache[$key];
} catch (\Exception $e) {
return $default;
}
}
public function watch(string $key, callable $callback): void {
// 長輪詢實現變更通知 (生產建議用 Consul PHP SDK)
$index = 0;
while (true) {
$response = $this->http->get("kv/{$key}", ['query' => ['index' => $index, 'wait' => '30s']]);
$index = $response->getHeaderLine('X-Consul-Index');
$data = json_decode($response->getBody()->getContents(), true);
if ($data) $callback($key, json_decode($data[0]['Value'] ?? '', true) ?? '');
}
}
}
.gitignore 必含 .env、.env.*、! .env.exampledefuse/php-encryption 加密 .env 敏感欄位,啟動時解密階段 1 (單體) : config.php 陣列 + .env (開發) → 立即可用 階段 2 (成長期) : 環境變數為主 + 型別安全 Config 物件 → 引入 phpdotenv、readonly class 階段 3 (微服務) : 共享配置庫 (GitOps) + Consul/Etcd 動態更新 → 分散式配置中心 階段 4 (平台化) : 內部開發者平台 (IDP) 統一配置管理介面 → 自服務配置、審計、回滾
配置管理演進的核心是 「敏感資訊脫離代碼庫」 與 「環境隔離零耦合」。從今天開始:
config.php 中的密碼、API Key、DSN 移至環境變數vlucas/phpdotenv 載入 .env (僅非生產環境)readonly class Config 提供型別安全存取這不只是最佳實踐,更是合規 (GDPR, SOC2) 與供應鏈安全的硬性要求。