如何在 GitHub push 後自動部署 Node.js？

將 Node.js 應用程式的 GitHub 儲存庫連到託管平台，就能在 push 後觸發部署。本文以 KamuiDash 為例，說明如何設定分支、工作目錄與啟動指令，並用公開網址確認版本。

本文內容

Push 之後會發生什麼？
建立小型 Node.js 應用程式
將範例推送到 GitHub
在 KamuiDash 設定服務
確認首次部署
推送變更並驗證新版
常見問題

Push 之後會發生什麼？

從 push 到上線 · 概念圖

推送到已連接的分支

平台安裝並啟動

用 HTTPS 網址驗證

託管平台監看已連接的分支，準備應用程式並啟動新部署。KamuiDash 可透過 GitHub 整合完成這些步驟。請先授權存取儲存庫並設定部署服務。

建立小型 Node.js 應用程式

下載範例，把內容放到儲存庫根目錄。範例使用內建 HTTP 模組，沒有資料庫或外部套件。

{
  "name": "small-node-deploy-example",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": { "start": "node server.js" },
  "engines": { "node": ">=22" }
}

import http from 'node:http';

const port = Number(process.env.PORT || 3000);
const server = http.createServer((req, res) => {
  const path = new URL(req.url, 'http://localhost').pathname;
  if (req.method !== 'GET') {
    res.writeHead(405, { 'content-type': 'application/json', allow: 'GET' });
    res.end(JSON.stringify({ error: 'Method not allowed' }));
    return;
  }
  res.setHeader('content-type', 'application/json; charset=utf-8');
  if (path === '/healthz') res.end(JSON.stringify({ ok: true }));
  else if (path === '/') res.end(JSON.stringify({ message: 'Hello from Node.js', version: 'v1' }));
  else { res.statusCode = 404; res.end(JSON.stringify({ error: 'Not found' })); }
});
server.listen(port, '0.0.0.0', () => console.log(`Listening on ${port}`));
process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 10000).unref();
});

伺服器在 0.0.0.0 監聽平台提供的 PORT。首頁會回傳訊息與版本，健康檢查會回傳 JSON。收到 SIGTERM 時，伺服器停止接受新連線並關閉。

請先安裝 Node.js 22 以上及 npm。這個沒有外部相依套件的範例能先驗證儲存庫權限及執行設定，再加入資料庫。需要保留的資料應存放在程序之外。

npm ci
PORT=3000 npm run start

從另一個終端機確認兩個路徑都回傳 HTTP 200，且首頁版本為 v1。

curl --fail http://127.0.0.1:3000/
curl --fail http://127.0.0.1:3000/healthz

將範例推送到 GitHub

建立空儲存庫，先略過 README 初始化。換成自己的儲存庫網址並完成 GitHub 驗證。若專案已有 Git，先確認目前分支和遠端。請提交鎖定檔，並避免將 .env 等機密資訊提交到 Git。GitHub 新增本機程式碼指南

git init
git branch -M main
git add package.json package-lock.json server.js .gitignore
git commit -m "Add small HTTP app"
git remote add origin https://github.com/YOUR_ACCOUNT/YOUR_REPOSITORY.git
git push -u origin main

在 KamuiDash 設定服務

在專案中建立 Node.js Web 伺服器。如果看不到儲存庫，請確認 GitHub App 的帳戶及儲存庫權限。GitHub App 安裝指南

KamuiDash 應用程式建立畫面，可選擇執行語言與 GitHub 儲存庫。 — 既有的 KamuiDash 範例顯示如何選擇執行環境與儲存庫。

設定	值
執行環境	Web 伺服器／Node.js
儲存庫與分支	範例儲存庫的 main
根目錄	package.json 位於儲存庫根目錄時留空
安裝指令	`npm ci`
啟動前指令	留空
啟動指令	`npm run start`
健康檢查	`/healthz`

若應用程式位於 apps/api，請將該資料夾設為根目錄，讓指令在包含 package.json 的位置執行。需要建置時，把建置指令加到安裝流程。KamuiDash Node.js 設定

指令的工作目錄 · 概念圖

儲存庫根目錄時留空

子目錄則設定 apps/api

對應 package.json 的位置

確認首次部署

等待部署完成後，開啟公開 HTTPS 網址的 / 和 /healthz，確認首頁回傳 v1。實際上線時，也應檢查使用者會操作的頁面和 API。

KamuiDash 靜態網站詳細資訊：執行狀態、公開網址、GitHub 分支與各次提交的部署紀錄。 — 既有靜態網站的詳細畫面顯示公開網址與部署記錄。

推送變更並驗證新版

將 server.js 的版本從 v1 改成 v2 後推送。

git add server.js
git commit -m "Change response version to v2"
git push origin main

在 KamuiDash 部署記錄中找到該 commit。成功後重新取得公開網址，確認 JSON 的版本為 v2。

現象	先確認
GitHub 看不到變更	遠端、分支與 commit
部署沒有開始	已連接的分支與 GitHub App 權限
建置失敗	安裝日誌、鎖定檔和工作目錄
啟動失敗	啟動日誌、PORT 及監聽位址
部署成功但回應仍是舊版	已部署的 commit、網址和快取

常見問題

需要 GitHub Actions 嗎？

KamuiDash 的 GitHub 整合可直接建置與部署。若上線前必須通過測試，請另外設定檢查與分支保護。

推送到 main 會立即上線嗎？

推送到已連接的分支會觸發部署。安裝與啟動需要時間，也可能失敗。分享前請確認已部署的 commit 和公開回應。團隊可以保護正式分支，僅合併已審查的變更。

可以加入資料庫嗎？

可以。請規劃資料庫連線、結構遷移與持久化驗證。FastAPI 與 PostgreSQL 部署指南

費用如何計算？

符合條件的應用程式與資料庫可試用 30 天的基本費用優惠。個人方案的 Nano Web 伺服器每個副本每 30 天未稅 $3 起。用量和附加項目另行估算。託管費用指南

排錯時先找出失敗階段與第一個明確錯誤。確認 v1 和 v2 都可上線後，再加入建置流程或資料庫。

驗證範圍為本機啟動及 HTTP 回應。GitHub 推送和新的 KamuiDash 部署不在此次測試範圍內。設定於 2026 年 11 月 2 日確認。

KamuiDash 是位於東京區域的 PaaS，可透過 GitHub 與 AI 整合公開 Web 應用程式。