Runtime 不是一個資料夾：為什麼程式在你的電腦能跑，換到伺服器卻失敗？

專題編輯：Derek Chou｜AI 技術與架構編輯

下載 Runtime 環境契約表（ZIP，內含 CSV）

從「可執行」追問：程式真正需要什麼？

設想一個企業內部的案件管理網站。前端瀏覽器顯示表單，後端接受 API 請求，資料庫保存案件。當員工說「我已下載專案，但畫面打不開」，他說的只是症狀，尚不足以定位原因。問題可能來自 Node.js 版本、套件未安裝、啟動指令、埠號衝突、缺乏資料庫連線資訊，也可能是作業系統限制。

Runtime 一詞有兩種常見語境。第一種指程式實際執行期間，與編譯、建置階段相對；第二種指提供程式執行能力的軟體環境，例如 JavaScript 的 Node.js Runtime、Java 的 JVM 或 Python 直譯器及其執行依賴。口語說「缺少 Runtime」，多半是第二種意思。但同一份環境契約還需要列出作業系統、執行權限、網路與外部服務。不要把這些不同層次都錯認成 Node.js 本身。

Node.js 官方將它定義為跨平台 JavaScript 執行環境，能在瀏覽器以外執行 JavaScript。這意味著 Node.js 是後端或工具程式的執行條件之一，而不是「後端」、「資料庫」或「雲端」的同義詞。網站也可以不使用 Node.js 服務端，改用其他語言或架構。參考：Node.js 官方介紹。

先分清 5 個層次，才不會裝錯東西

第一層是原始碼，例如 server.js、package.json 與其他專案檔。第二層是執行程式的 Runtime 或直譯器，例如 Node.js。第三層是套件與依賴，例如透過套件管理器安裝的程式庫。第四層是系統設定和資源，包括作業系統、環境變數、檔案路徑、連接埠、CPU、記憶體與存取權限。第五層是外部依賴，例如資料庫、API、內部網路與驗證服務。這五層可能同時存在，但故障時要逐層排除。

因此，「安裝 Node.js 22 就能完成全端專案」不是充分條件。特定專案是否相容，必須先讀 package.json 的 engines、套件說明與團隊文件，再確認資料庫與服務設定。即使版本符合，未安裝依賴、沒有必要授權或連不到測試資料庫，仍可能失敗。反過來說，若一個專案只是純靜態 HTML，瀏覽器即可呈現頁面，未必需要在正式服務環境執行 Node.js。

開發、建置、執行、部署，不是同一件事

開發是修改原始碼；建置是依專案需求將資源處理成可用成品；執行是讓程式在環境中處理請求；部署則是把版本交付至指定目標並啟用服務。Node.js 可以同時出現在多個環節。例如前端開發時用 Node.js 執行建置工具，部署後只由瀏覽器執行 JavaScript，伺服器不一定還要有 Node.js。另一個後端專案則可能在正式伺服器持續使用 Node.js 接受 HTTP 請求。

這也解釋容器、虛擬機與雲端的關係。Docker 容器通常將應用程式與部分執行依賴一起封裝，以減少「在某台電腦才可運作」的環境落差；它不是 Runtime 的同義詞，也無法自行消除網路、秘密管理、權限及外部資料庫差異。雲端是可供使用的運算與服務資源，仍須指定執行條件與部署位置。

一份真正可交接的環境契約應寫什麼？

對專案負責人而言，最有價值的不是要求每個人背誦術語，而是把可核實資訊寫成一張表。建議為每個專案保留下列欄位：

表格中的命令是常見範例，不保證能在每一個專案執行。尤其不要把實際密碼、API 金鑰或連線憑證提交到 Git 儲存庫。

讀懂三種常見故障，減少無效重裝

若出現 command not found: node，應先查作業系統是否找得到 Node.js 可執行檔與環境路徑，不宜立即假定原始碼壞掉。若出現 Cannot find module，需確認依賴有無正確安裝、專案路徑是否正確及套件名稱是否存在。若程式已啟動卻回傳資料庫連線失敗，則應檢查配置、網路、帳號權限與資料庫服務狀態；盲目升級 Runtime 可能讓問題更複雜。

企業教學可安排一個低風險的分組練習：每組取得同一個不含敏感資料的樣本專案，先根據文件核對執行條件，再嘗試啟動。教師刻意移除一項環境設定，要求學員從錯誤訊息找出缺件，最後更新交接文件。成果不是「某一台電腦成功跑出畫面」，而是另一組能根據相同契約重現啟動過程。

給主管的決策：要買平台之前，先確認可移植性

若專案只依賴一位工程師的電腦或私人帳號，離職、換機、資安事件及雲端遷移都會放大風險。環境契約不保證所有問題消失，但能減少未記錄的隱性依賴。可以把「第二台受控電腦可依文件啟動」、「測試資料和正式資料隔離」、「秘密不進版本庫」、「異常有可追溯錯誤碼」列為首次交付的最低要求。

Runtime 的管理意義，並非多安裝一種軟體，而是讓程式從依賴個人的偶然成功，變成在受控條件下可以重現的組織能力。

一個「同樣的程式碼」卻跑出不同結果的完整情境

以下是假想的公司內部新專案，目的是示範環境盤點，不代表已在某企業實測。A 同仁在 macOS 建立一個案件查詢 API，B 同仁在 Windows 接手測試。B 成功取得 Git 儲存庫後執行啟動命令，卻得到「無法載入必要模組」的錯誤。管理者很容易把責任歸給 B 不熟悉電腦，但這個現象其實有多種可能。

先看是否取得完整原始碼與鎖定檔，並辨認專案入口。接著核對 Node.js 版本是否符合文件，以及依賴套件是否在 B 的工作目錄成功安裝。如果錯誤從模組缺失變成資料庫連線失敗，代表程式已往前推進至另一層，下一步需要檢查的是環境變數、資料庫狀態與網路，而不是重複下載同一個 ZIP。

若 B 成功看到健康檢查回應，仍不能直接判定全端成果完成。管理者應指定一筆合成案件資料，驗證從瀏覽器輸入、API 處理到資料庫讀取的結果是否一致，並保存驗收紀錄。這個過程依序回答「能啟動嗎」、「能連接嗎」及「功能正確嗎」三個不同問題。越是團隊多人接手，越不能把這三個問題混成一句「程式有跑起來」。

Runtime 與執行環境的四個常見誤解

誤解一：Node.js 版本越新越好。 新版提供新功能與安全維護，但既有專案仍須依實際支援範圍選版。企業不應只因一位學員已裝新版就略過相容性測試。版本選擇需同時考量開發工具、相依套件、部署平台和安全更新政策。

誤解二：有 GitHub 就不需要設定環境。 GitHub 儲存庫主要保存程式碼與版本歷史，不會自動替每一台電腦安裝相同 Runtime、配置相同網路，也不代表 GitHub 帳號可直接登入所有雲端服務。

誤解三：在本機可運作，就能直接上雲端。 雲端部署還需解決服務入口、環境變數、資料庫連線、資源限制、秘密、網路與健康檢查。平台可能協助處理部分細節，但責任並未消失。

誤解四：容器保證任何地方都完全相同。 容器有助於封裝應用程式與相依環境，仍可能受到 CPU 架構、核心功能、網路政策、外部服務與資料差異影響。容器映像可重現，只是交付可信度的一部分。

交接時最容易漏掉的不是版本，而是秘密管理

許多專案需要資料庫密碼或 API 金鑰。為了讓新學員成功啟動，直接把密碼寫進 README、ZIP 或程式碼雖然方便，卻會產生存取與洩露風險。比較合適的做法，是提供不含敏感值的設定欄位範本，另外透過授權機制交付測試憑證。應將「誰可以領取」、「何時失效」、「如何輪替」一併納入部署文件。若企業環境完全封閉、不能使用公共雲端，教學就要使用內網或本機可運作的假資料和服務，而不是要求學員繞過網路限制。

常見提問

Runtime 與 Framework 有何不同？ Runtime 提供執行條件；Framework 提供應用開發的結構與常用功能。以 JavaScript 生態系為例，Node.js 與以它為基礎執行的後端框架是不同層次。兩者可以搭配，但不能互相取代。

Runtime 與作業系統相同嗎？ 不同。Node.js 在作業系統之上運作，並透過系統提供的能力存取檔案、網路等資源。即使 Runtime 版本一致，權限或作業系統差異仍可能影響結果。

什麼時候可以說環境準備完成？ 至少有經確認的版本與依賴、符合政策的設定、可用的測試服務、成功啟動的回執及可重現的基本功能測試。完整門檻應由專案風險決定。

參考資料

1. Node.js：Introduction to Node.js。
2. Node.js：Learn Node.js。
3. GitHub Actions：Understanding GitHub Actions。

圖片與素材說明

封面為本篇原創概念插畫，非實際機房、系統操作畫面或特定企業部署紀錄。