使用 ServBay 建立並執行 Koa.js 專案

ServBay 是一套支持 macOS 與 Windows 的本機 Web 開發環境，整合多種常用開發套件，包括 Node.js 執行時與多種資料庫。本文將帶您快速學習如何善用 ServBay 提供的便利環境，高效建立、運行與管理您的 Koa.js 專案。

什麼是 Koa.js？

Koa.js 是由 Express.js 團隊開發的下一代 Node.js 網頁框架，以簡潔、富表現力及功能強大聞名，非常適合建構 Web 應用和 API。Koa.js 充分運用了現代 JavaScript 的特色，特別是 async/await 語法，讓非同步作業及中介軟體的撰寫更簡單，程式結構清晰易維護。

Koa.js 主要特色

• 以 async/await 為核心： 設計圍繞 async/await，非同步處理流程直覺流暢。
• 精簡核心庫： 僅包含基礎功能，透過模組化中介軟體擴充所需功能。
• 強大的中介軟體機制： 採用串接式中介軟體，請求處理流程靈活俐落。
• 專注 Web 應用： 針對 Web 與 API 開發，避免多餘功能。

使用 Koa.js，有助於開發者高效打造高性能且易於維護的網頁服務。

使用 ServBay 建置 Koa.js 開發環境

ServBay 為 Node.js 開發者提供即裝即用的環境，整合 Node.js 執行時與常見資料庫服務。搭配 ServBay 的**網站（Website）**功能，可運用自定義網域與 SSL 憑證輕鬆存取您的本地 Koa.js 專案。

前置需求

開始前，請先完成下列步驟：

1. 安裝 ServBay： 造訪 ServBay 官方網站 下載並安裝最新版本。
2. 安裝 Node.js 套件： 開啟 ServBay 應用，至**套件（Packages）**管理頁，確認已安裝所需 Node.js 版本，未安裝者請選擇後點擊安裝。
3. 熟悉 ServBay 操作： 理解如何在 ServBay 啟動/停止服務及管理網站（Website）。

建立 Koa.js 專案

以下使用 ServBay 建議的網站根目錄 /Applications/ServBay/www 來存放專案檔案。

1. 初始化專案目錄

   開啟終端機（Terminal），切換到 ServBay 的網站根目錄，建立新專案資料夾（如 servbay-koa-app），進入該資料夾並初始化一個 Node.js 專案：

   cd /Applications/ServBay/www
   mkdir servbay-koa-app
   cd servbay-koa-app
   npm init -y

   npm init -y 可快速產生預設的 package.json 檔案。

2. 安裝 Koa.js

   在專案根目錄 servbay-koa-app，利用 npm 安裝 Koa.js 及其型別定義（TypeScript 用戶可選）：

   npm install koa
   # 若使用 TypeScript，安裝型別定義
   # npm install @types/koa --save-dev

3. 建立應用入口文件

   在根目錄 servbay-koa-app 新建 app.js，並加入簡單 Koa.js 程式碼：

   const Koa = require('koa');
   const app = new Koa();
   
   // 中介軟體：記錄請求資訊
   app.use(async (ctx, next) => {
     const start = Date.now();
     await next();
     const ms = Date.now() - start;
     console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
   });
   
   // 中介軟體：處理根路徑請求
   app.use(async ctx => {
     ctx.body = 'Hello from ServBay Koa.js App!';
   });
   
   // 定義連接埠，優先採用環境變數 PORT
   const port = process.env.PORT || 3000;
   
   // 啟動 HTTP 伺服器
   app.listen(port, () => {
     console.log(`Koa.js server running on http://localhost:${port}`);
     console.log(`Project path: ${__dirname}`);
   });

   這份程式碼建立了一個 Koa 應用，包含兩個中介軟體：一用以記錄請求時長與路徑，另一回應根路徑 /，輸出 "Hello from ServBay Koa.js App!"。服務將監聽環境變數 PORT 指定或預設的 3000 埠。

進入開發模式

開發時，通常會在本地啟動 Node.js 程序運行 Koa.js，並透過 ServBay **網站（Website）**功能存取。

1. 啟動 Koa.js 開發伺服器

   開啟終端機，進入專案目錄 servbay-koa-app，使用 node 指令執行 app.js。建議指定特定埠號（如 8585）以避免衝突並利於 ServBay 設定：

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8585 node app.js

   終端應顯示如 Koa.js server running on http://localhost:8585，代表伺服器已在 8585 埠啟動。請保持此終端開啟以維持服務運作。

2. 設定 ServBay 網站（Website）反向代理

   若欲以自定義網域存取在 localhost:8585 之 Koa.js 應用，須於 ServBay 新增一個**網站（Website）**並設定反向代理：

   • 開啟 ServBay 應用程式。
   • 轉至**網站（Website）**頁面。
   • 點選左下角 + 新增網站。
   • 設定如下：
     • 名稱 (Name): ServBay Koa.js Dev Site
     • 網域 (Domain): servbay-koa-dev.servbay.demo（建議使用 .servbay.demo 結尾，ServBay 會自動產生 SSL 憑證）
     • 類型 (Type): 選擇 反向代理 (Reverse Proxy)
     • IP 位址 (IP Address): 127.0.0.1（指向本機 Node.js）
     • 連接埠 (Port): 8585 （指向 Koa.js 應用監聽埠）
     • 根目錄 (Document Root): 反向代理型態可空白或填 /Applications/ServBay/www/servbay-koa-app
   • 點擊儲存。
   • 如系統提示即時套用，請確認套用設定。

   完成後，ServBay 會自動更新本機 hosts 檔，將 servbay-koa-dev.servbay.demo 指向 127.0.0.1，並使用 Caddy 或 Nginx 進行反向代理至 8585 埠。 .servbay.demo 網域下，ServBay User CA 將自動簽發並信任 SSL 憑證，可安全使用 HTTPS。

   詳細步驟可參見 ServBay 文件之新增 Node.js 開發網站（請選英語版本）。

3. 存取 Koa.js 開發網站

   開啟瀏覽器，前往 https://servbay-koa-dev.servbay.demo。

   若設置無誤，頁面應出現 "Hello from ServBay Koa.js App!"。代表現已可藉 ServBay 網站功能存取本機執行之 Koa.js 開發伺服器。當您修改 app.js 並重啟 Node.js 後，刷新網頁便可看到更新。

模擬部署生產版本

如需模擬生產環境，可調整連接埠、環境變數與啟動方式。ServBay 反向代理亦適用於此。

1. 啟動 Koa.js 生產伺服器（模擬）

   在另一終端關閉原有開發伺服器，接著以模擬生產模式（用不同埠如 8586 並設置 NODE_ENV）啟動：

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8586 NODE_ENV=production node app.js

   即會啟動監聽 8586 埠的 Koa.js，模擬生產狀態運行。

2. 設定 ServBay 網站（Website）反向代理（生產模擬）

   同方式於 ServBay 為生產模擬環境新建網站：

   • 開啟 ServBay，進入網站（Website）。
   • 點左下 + 新增網站。
   • 設定：
     • 名稱 (Name): ServBay Koa.js Prod Site
     • 網域 (Domain): servbay-koa-prod.servbay.demo（如有自有網域亦可用 ServBay 的 ACME/Let's Encrypt 輕鬆申請 SSL 憑證）
     • 類型 (Type): 反向代理 (Reverse Proxy)
     • IP 位址 (IP Address): 127.0.0.1
     • 連接埠 (Port): 8586（指向生產 Koa.js 埠）
     • 根目錄 (Document Root): 可空白或填專案路徑
   • 儲存並套用

   使用 .servbay.demo 仍採用 ServBay 用戶 CA 憑證。如用公開網域，ServBay 支持 ACME (如 Let's Encrypt) 申辦免費 SSL/TLS 憑證，完整模擬正式生產環境。詳情參見 ServBay 文件使用 SSL 保護網站。

3. 存取 Koa.js 生產網站（模擬）

   瀏覽至 https://servbay-koa-prod.servbay.demo。

   應能看到與開發環境同樣內容，僅此次請求已經由 ServBay 反向代理轉發至 8586 端口之 Node.js 程序處理。

資料庫連線

ServBay 整合多種常用資料庫，包括 MongoDB、Redis、MariaDB（MySQL 相容）、PostgreSQL。於 Koa.js 專案中連線這些資料庫十分方便，因皆在本地執行，且預設可用 localhost 連線。

示例代碼如下，請確保您已在 ServBay **套件（Packages）**頁安裝所需資料庫並執行中。

1. 連接 MongoDB

   於 Koa.js 專案目錄安裝 MongoDB Node.js 驅動（例如 mongoose 或 mongodb）：

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # 或 npm install mongodb

   在 app.js 增加連線程式：

   // 使用 Mongoose 連接 MongoDB
   const mongoose = require('mongoose');
   
   // ServBay 預設 MongoDB 無須認證，資料庫名可自訂
   mongoose.connect('mongodb://localhost:27017/servbay-koa-app', {
     useNewUrlParser: true,
     useUnifiedTopology: true
   })
   .then(() => console.log('Connected to MongoDB'))
   .catch(err => console.error('MongoDB connection error:', err));
   
   // 注意：一般連線程式多寫在啟動邏輯中
   // 並於連線成功後才啟動監聽埠口。

   ServBay 預設做法，MongoDB 通常在 27017 埠且無認證需求。只需指定資料庫名，不存在則自動建立。

2. 連接 Redis

   安裝 Redis Node.js 客戶端：

   cd /Applications/ServBay/www/servbay-koa-app
   npm install redis

   連線 Redis 伺服器：

   // 使用 redis 客戶端連線 Redis
   const redis = require('redis');
   
   // 建立 Redis 客戶端，預設連線 localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // ServBay 預設 Redis 埠為 6379
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // 連線 Redis 伺服器
   client.connect();
   
   // 注意：實際應用中，建議等連線成功後才執行 Redis 操作
   // 如搭配 async/await 與 client.connect()

   默認安裝之 Redis 監聽 6379 埠且無密碼。

3. 連接 MariaDB (或 MySQL)

   MariaDB 為 MySQL 分支，API 相容度高。ServBay 內建 MariaDB，可視同 MySQL 使用。

   安裝 Node.js 驅動：

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # 或 npm install mysql2 (更推薦)

   用 mariadb 驅動連線：

   // 使用 mariadb 客戶端連線 MariaDB
   const mariadb = require('mariadb');
   
   // ServBay 預設 MariaDB root 密碼為 'password'
   const pool = mariadb.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // 請先建立資料庫或自訂
     connectionLimit: 5
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB");
       conn.release(); // 釋放連線回pool
     })
     .catch(err => {
       console.error("MariaDB connection error:", err);
     });
   
   // 注意：連線 pool 用法皆異步

   用推薦 mysql2 驅動連線：

   // 使用 mysql2 客戶端連線 MariaDB/MySQL
   const mysql = require('mysql2/promise'); // 使用 promise 版本
   
   // ServBay MariaDB root 預設密碼 'password'
   const pool = mysql.createPool({
     host: 'localhost',
     user: 'root',
     password: 'password',
     database: 'servbay_koa_app', // 請先建立資料庫
     waitForConnections: true,
     connectionLimit: 10,
     queueLimit: 0
   });
   
   pool.getConnection()
     .then(conn => {
       console.log("Connected to MariaDB/MySQL using mysql2");
       conn.release(); // 釋放連線回pool
     })
     .catch(err => {
       console.error("MariaDB/MySQL connection error:", err);
     });
   
   // 注意：ServBay 預設 root 密碼可於 GUI 資料庫設定檢視或修改。
   // 實際專案建議以環境變數管理密碼，勿硬編。

   ServBay MariaDB 預設 監聽 3306 埠，密碼可於 ServBay 資料庫管理界面查詢。請善用工具（如 TablePlus、DBeaver 等）手動新增資料庫如 servbay_koa_app。

4. 連接 PostgreSQL

   安裝 Node.js 驅動：

   cd /Applications/ServBay/www/servbay-koa-app
   npm install pg

   連線 PostgreSQL：

   // 使用 pg 客戶端連線 PostgreSQL
   const { Pool } = require('pg');
   
   // ServBay 預設 PostgreSQL 用戶 'user' 密碼 'password'
   const pool = new Pool({
     user: 'user', // ServBay 預設
     host: 'localhost',
     database: 'servbay_koa_app', // 請先建立
     password: 'password', // ServBay 預設密碼
     port: 5432, // ServBay 預設 PostgreSQL 埠
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release(); // 釋放連線回 pool
   });
   
   // 注意：ServBay 預設 PostgreSQL user 密碼可於 GUI 資料庫設定查詢與修改。
   // 建議密碼管理勿硬編。

   ServBay PostgreSQL 默認在 5432 埠與預設帳密，可於 GUI 查閱。亦請自行新增對應資料庫。

管理 ServBay 資料庫

除程式連線外，亦可用圖形工具管理 ServBay 資料庫。ServBay 資料庫預設監聽 127.0.0.1 或 localhost，用 GUI 顯示之埠與帳密即可連接。

• 查詢/修改預設密碼： 開啟 ServBay，點選相應資料庫套件後點設定齒輪，可見預設 root (MariaDB) 或 user (PostgreSQL) 密碼，可直接修改。
• 新建資料庫/用戶： 使用 TablePlus、DBeaver、pgAdmin、MongoDB Compass 等工具連線 ServBay 資料庫，利用 SQL 或 GUI 新增資料庫、用戶、資料表。

注意事項

• 埠號衝突： 請確認 Koa.js 應用所選連接埠（如 8585, 8586）未被其他程式佔用。
• ServBay 狀態： 保證 ServBay 應用本身、所需 Node.js 套件及資料庫服務均正常執行。
• hosts 檔案： ServBay 會自動管理 /etc/hosts，如遇網域解析問題請檢查有無對應紀錄。
• 防火牆： macOS 內建或第三方防火牆勿阻擋 ServBay 或 Node.js。
• 檢視日誌： 遇問題可檢查 ServBay 應用之日誌，以及 Node.js 終端輸出，有助診斷。

常見問題解答 (FAQ)

• 問：為什麼要利用 ServBay 反向代理存取 Koa.js 專案？

  答： 利用反向代理（ServBay 網站功能）有以下優點：

  1. 模擬正式環境： 使用自訂網域（如 .servbay.demo 或自有網域）更貼近實際部屬方式。
  2. SSL 支援： ServBay 可為本地站台自動配置 SSL（含 ServBay User CA 或 Let's Encrypt），讓開發階段就能測試 HTTPS。
  3. 統一管理： 集中管理所有本地開發站台，簡單快速。
  4. 隱藏高埠： 外部（或瀏覽器）使用標準 80/443 埠，實際反向代理到 Node.js 進程的高埠。

• 問：可否不反向代理，直接用 localhost:PORT 開發？

  答： 可以。若 Koa.js 應用直接監聽埠（如 3000 或其他指定）可直用 http://localhost:PORT 存取測試。但會失去 ServBay 提供之自訂網域、自動 SSL、日誌管理等便利。在追求貼近真實部署場景時，建議仍用 ServBay 反向代理。

• 問：ServBay 預設資料庫密碼是什麼？怎麼修改？

  答： ServBay 預設密碼可於應用內資料庫介面查得。點選資料庫（如 MariaDB 或 PostgreSQL）旁的設定齒輪，在資訊視窗即可見預設帳密，並可直接修改。建議安全起見，請修改預設密碼。

總結

經本文引導，您已學會如何利用 ServBay 在 macOS 上建置 Koa.js 開發環境。我們從零開始建立 Koa.js 應用，並運用 ServBay 網站功能設定反向代理，成功以自訂網域與 HTTPS 存取本地運行的 Koa.js 開發與模擬生產環境，亦了解連線 ServBay 內建各類主流資料庫的方式。

ServBay 為 Node.js 開發者打造集成、易管理的本地開發環境，專注於程式本身，不必煩惱複雜環境配置。善用 ServBay 強大功能，將大幅提升開發效率！