pthreads v3/v4 僅支持 PHP 7.2+（ZTS 線程安全版），且必須在 CLI 模式下運行（非 Web SAPI）。本文詳述從下載、版本匹配、安裝、環境變量配置到驗證的全流程，避開 90% 的坑。
php -i | findstr "Thread Safety" # 輸出應為：Thread Safety => enabled # 若為 disabled，需重裝 ZTS 版 PHP（下載檔名含 -zts-）
同時確認：
php -i | findstr "Compiler"php -i | findstr "Architecture"4.1.4 (PHP 8.0/8.1) 或 3.2.1 (PHP 7.2/7.3/7.4)。pthreads-<版本>--zts-<編譯器>-<架構>.zip pthreads-4.1.4-8.2-zts-vs16-x64.zipphp_pthreads.dll 和 pthreadVC3.dll (v4) / pthreadVC2.dll (v3)。php_pthreads.dll → PHP 安裝目錄 ext/。pthreadVC3.dll → PHP 安裝目錄（與 php.exe 同級）並 C:\Windows\System32\（或加入 PATH）。php.ini，在 [ExtensionList] 區域添加：extension=pthreads ; 推薦同時啟用 zend_extension=opcache
php -m | findstr pthreads 應顯示 pthreads。pthreadVC3.dll 必須在系統 PATH 中，否則啟動報錯 The program can't start because pthreadVC3.dll is missing。
# PowerShell 管理員執行
$phpDir = "C:\php-8.2.10" # 你的 PHP 目錄
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path","Machine") + ";$phpDir", "Machine")
# 或手動：此電腦→屬性→高級系統設置→環境變量→系統變量 Path→編輯→新增 PHP 目錄
<?php
// 僅 CLI 運行
if (php_sapi_name() !== 'cli') {
die("pthreads 僅支持 CLI 模式\n");
}
class AsyncTask extends Thread {
public function __construct(public int $id, public int $delay) {}
public function run(): void {
sleep($this->delay);
echo "Task {$this->id} completed after {$this->delay}s\n";
}
}
$tasks = [
new AsyncTask(1, 2),
new AsyncTask(2, 1),
new AsyncTask(3, 3),
];
$start = microtime(true);
foreach ($tasks as $t) $t->start();
foreach ($tasks as $t) $t->join();
echo "Total time: " . round(microtime(true) - $start, 2) . "s\n";
// 預期 ~3s (並發) 而非 6s (串行)
運行：php test_threads.php，輸出應顯示任務交錯完成，總耗時 ≈ 最長單任務時間。
| 錯誤現象 | 原因 | 解決 |
|---|---|---|
| PHP Warning: PHP Startup: Unable to load dynamic library 'pthreads' | 版本不匹配（非 ZTS、PHP 版本錯、編譯器錯、架構錯） | 重新核對 php -i 信息，下載完全一致的 DLL |
| Class 'Thread' not found | 擴展未加載或 php.ini 未生效 | php --ini 確認載入的 ini 文件，檢查 extension=pthreads 行 |
| pthreadVC3.dll missing | DLL 不在 PATH | 複製到 System32 或加入 PATH 並重啟終端 |
| Fatal error: pthreads only works in CLI | 在 Apache/FPM 中嘗試使用 | 僅 CLI 腳本使用；Web 多進程請用 Swoole/Workerman/ReactPHP |
| Segmentation fault / Crash | 線程安全違規：跨線程訪問非線程安全資源（PDO 連接、GD 圖片資源等） | 每個線程內部獨立創建資源，或使用 Pool/Worker 模式傳遞可序列化數據 |
class DataProcessor extends Threaded {
public function __construct(public array $data) {}
public function run(): void {
// 模擬耗時計算
$this->result = array_sum($this->data) * 1.5;
usleep(100000);
}
}
$pool = new Pool(4); // 4 個工作線程
$tasks = [];
for ($i=0; $i<20; $i++) {
$tasks[] = new DataProcessor(range(1, 1000));
$pool->submit($tasks[$i]);
}
$pool->shutdown(); // 等待所有完成
$total = array_sum(array_column($tasks, 'result'));
echo "Processed 20 tasks, total: $total\n";
Pool 自動管理線程生命周期、任務隊列、結果收集，避免手動 start/join 易出錯。
| 方案 | 適用場景 | 優點 | 缺點 |
|---|---|---|---|
| pthreads | CLI 計算密集型、科學計算、批量處理 | 原生線程、共享內存、真並行 | 僅 CLI、ZTS 必須、擴展維護緩慢 |
| Swoole / OpenSwoole | Web 服務器、WebSocket、異步 IO、微服務 | 協程+進程、高性能、生態豐富 | 學習曲線陡、需重寫阻塞代碼 |
| Workerman | 長連接、即時通訊、物聯網網關 | 純 PHP、易上手、穩定 | 單進程單線程、CPU 密集型需多進程 |
| ReactPHP / Amp | 異步 HTTP 客戶端、事件驅動應用 | 純 PHP、Promise/Generator 風格 | 無真並行、CPU 密集型需進程分發 |
| Gearman / RabbitMQ + Worker 進程 | 分佈式任務隊列、異步作業 | 跨語言、持久化、可擴展 | 基礎設施複雜、延遲較高 |
Windows PHP 安裝 pthreads 核心在於 「四個一致」：PHP 版本、ZTS、編譯器、架構。安裝後務必配置 PATH 加載 pthreadVC3.dll。僅在 CLI 批量計算場景使用；Web 高併發請轉向 Swoole/OpenSwoole 生態。
