概念位置

接手 PHP 專案時，Composer 是判斷「專案依賴了什麼、版本有沒有已知漏洞」的入口。專案根目錄通常有三個 Composer 相關的檔案：

可觀察訊號

接手專案時如果根目錄有 composer.json 但沒有 vendor/，代表需要先跑 composer install 才能讓專案運作。如果連 composer.lock 都沒有，代表套件版本沒有鎖定——每次安裝可能拿到不同版本。

設計責任

兩個常用指令的差別：

• composer install：按 composer.lock 安裝確切版本。用於部署和接手——確保每台機器安裝的版本一致。
• composer update：重新解析 composer.json 的版本範圍、更新到最新的符合版本、改寫 composer.lock。用於主動升級依賴。

接手時的關鍵操作：

• composer audit：掃描已安裝套件的已知安全漏洞
• composer outdated：列出可更新的套件及其最新版本

鄰卡

• .env：Composer 管套件、.env 管設定值，兩者都是 PHP 專案的基礎設施
• php.ini / .user.ini：Composer 需要 PHP CLI 執行，php.ini 的 memory_limit 和 max_execution_time 會影響 Composer 能不能跑完

差異的四個層次

套件管理器：每個平台各有原生解

macOS 用 Homebrew、Arch 用 pacman、Debian/Ubuntu 用 apt、Fedora 用 dnf。安裝指令、確認旗標、資料庫同步模型都不同，其中兩個差異會直接咬到自動化腳本：

• 非互動旗標不對稱：apt 的慣例是 -y，pacman 是 --noconfirm。腳本只寫了其中一邊，換平台就會卡在確認提示——非 TTY 環境下（SSH 一行式、CI、無人值守）沒人回答 [Y/n]，pacman 直接以錯誤結束。
• 資料庫同步模型不同：Arch 是 rolling release 且鏡像不保留舊版檔案，裝機當下的套件資料庫幾天內就會指向已被輪替掉的檔名，安裝時收到 404（failed retrieving file）。修法是安裝前先 pacman -Syu 同步資料庫並全系統升級——只 -Sy 不 -u 會造成 partial upgrade（新資料庫裝新套件、舊系統缺新依賴）。Debian stable 的套件庫凍結、沒有這個時序問題，但代價是版本舊。

套件名稱：同一個工具、各發行版各叫各的

Debian 的重命名還會連執行檔一起改（fdfind、batcat），所以連 shell alias 與腳本內的指令呼叫都要跟著分歧。維護跨發行版清單的可靠做法是逐台實測建立——憑印象抄一份對照表，漂移只是時間問題。

套件存在性：有些概念只存在於特定平台

Hyprland 在 Arch 官方 repo、Fedora 要 COPR、Debian stable 沒有；Quickshell 只有 Arch 打包。反過來，macOS 的 cask app（GUI 應用程式）概念在 Linux 對應的是各桌面環境自己的生態。這層差異沒有翻譯的空間——桌面層的清單是平台專屬的維護對象。

存在性差異還有一個容易漏看的軸：CPU 架構。發行版 repo 有這個工具、不代表它在你的架構上存在——尤其是專有軟體的二進位發行。實測案例：Arch aarch64（ALARM）的 repo 有 spotify-launcher（工具本身有 aarch64 建置），但它要下載的 Spotify 官方 client 只發 x86_64/i386 deb，實跑直接回報 There are no packages for your cpu's architecture (cpu="aarch64", supported=["amd64", "i386"])。這類失敗的判讀重點是分清「工具沒打包」跟「工具打包了、它依賴的專有 blob 沒有這個架構」——前者可能有 AUR / 第三方 repo 補、後者只能找替代路徑（Spotify 的替代是 Web Player + 從 ChromeOS 鏡像抽出的 arm64 Widevine CDM）。DRM、GPU driver、印表機 driver 這類含專有二進位的軟體，在非 x86_64 架構上都要先查架構支援再排進安裝清單。

版本節奏：rolling 與 stable 的行為差

Arch rolling 永遠最新，Debian stable 的同名工具可能舊兩年。版本差會讓 config 語法對不上（新版工具的設定選項在舊版不存在）、也會讓「照著文件做卻失敗」——文件寫的是新版行為。除錯時看到「同一份 config 在 A 機器能跑、B 機器報錯」，先比對兩邊的工具版本再懷疑 config 本身。

除錯前先定平台

跨平台差異對除錯的意義：判讀工具與修法都是平台相依的，先確認自己站在哪，再開始查。 三條指令建立座標：

1cat /etc/os-release        # 發行版與版本（Linux）
2uname -m                   # CPU 架構：x86_64 / aarch64（套件生態差很多）
3command -v pacman apt-get dnf brew   # 哪個套件管理器在場

架構那條容易被忽略：aarch64（ARM）的套件生態比 x86_64 小——Homebrew on Linux 對 aarch64 沒有預編譯 bottle、AUR 部分套件不支援 ARM。在 ARM 機器上照 x86 的教學走，會在意想不到的地方碰壁。

Bootstrap 的分歧設計判準

把差異收進腳本架構的三條判準，決定每段邏輯住在哪：

1. 安裝手段跨平台一致（git clone、curl installer、stow 部署）→ 進共通層，一份邏輯全平台用
2. 只是套件名或套件管理器不同 → 各平台一份安裝腳本 + 一份套件清單，獨立維護、分歧不寫進共通層的 if/else
3. 概念只存在於某平台（Hyprland、cask）→ 只出現在該平台清單的桌面層

這個切法的維護成本結構：共通層改一次全平台生效；平台層只在你真的用那個平台時才付維護成本。沒有實測機器的發行版不預先建清單——那種清單沒有實測支撐、注定漂移。

統一層的誘惑與代價

「用一個跨平台套件管理器統一所有機器」聽起來能消掉整個分歧層，實際的適用邊界很窄。Homebrew 支援 Linux，但它在 Arch 上會建一套與 pacman 平行的套件世界（獨立 prefix、重複的函式庫、PATH 互搶），而且對 aarch64 Linux 沒有 bottle、全部從原始碼編譯。它真正的適用場景是「發行版套件太舊」（如 Ubuntu LTS 上要新版工具）或「沒有 root 權限」。Nix 能做到真正的跨平台一致，代價是整套心智模型重學。判準是：分歧層的維護成本（每個發行版一份清單）低於統一層的引入成本時，保持原生套件管理器 + 分平台清單。

下一步路由

• Bootstrap 腳本本身的設計（log 落地、錯誤定位）見可除錯的 bootstrap
• 最小系統缺什麼、怎麼驗證見最小安裝後的工具驗證與補足
• 出問題時的判讀紀律見 Linux 除錯與診斷
• dotfile repo 怎麼同時服務 macOS 與 Linux 見一個 repo 管理跨平台環境