在 macOS 上嘗試本地架設 Ghost 部落格時,許多人會卡在最後一步:執行 npm start 後終端機拋出一個找不到 node_sqlite3.node 的錯誤。這個問題的根源不在 Ghost,而在它的其中一個相依套件安裝失敗。以下記錄成因與解法。

錯誤訊息
ERROR: Cannot find module 'xxxxxxxx./binding/Release/node-v11-darwin-x64/node_sqlite3.node'
安裝 node 與 npm
這個步驟通常沒問題。過程中可能出現 $PATH 環境變數相關的提示,但一般很快就能解決——確認 node 與 npm 的安裝路徑已加入 PATH,並用 node -v 與 npm -v 驗證即可。
Ghost 安裝時的報錯
下載 Ghost 後在終端機進入目錄,執行:
npm install --production
整個流程跑了兩三次,看似成功,但執行 npm start 時依然無效,並拋出前述錯誤。
原因分析
關鍵在於 sqlite3 這個原生模組安裝失敗。sqlite3 需要下載對應平台的預編譯二進位檔,其來源之一是 Amazon S3。在網路受限的環境下(即使開了全域代理),這個下載常會靜默失敗——npm 不會因此中斷整個安裝流程,於是就留下一個「看起來裝好了、實際上缺檔案」的狀態。
解決方案
手動取得 sqlite3 的編譯產物,放到 npm 期望的位置:
1. 下載對應版本的 sqlite3 檔案並解壓。
2. 把它放進 Ghost 安裝目錄下的 node_modules/sqlite3/lib/binding/Release/。
3. 重新執行 npm start。
更根本的解法
手動補檔雖然有效,但每次重裝都得重來一遍。較長久的做法有三個方向。一是換用 npm 鏡像源:npm config set registry https://registry.npmmirror.com,並設定 sqlite3_binary_host_mirror 指向國內鏡像,讓二進位檔下載走可達的路徑。二是改用 yarn 或 pnpm,它們在原生模組的處理與快取機制上較健壯。三是直接從原始碼編譯,在該套件目錄下執行 npm rebuild sqlite3 --build-from-source,前提是已透過 Xcode 安裝好編譯工具鏈。
最後提醒一點:Ghost 的版本迭代相當頻繁,早期版本對 Node.js 的版本要求與現在差異很大。若你只是想在本地寫作測試,用官方 Docker 映像會比手動處理相依性省事得多——docker run -d -p 2368:2368 ghost:latest 一行就能跑起來,資料也可透過 volume 持久化。