使用 ServBay 在 macOS 本機建立並運行 NestJS 專案

NestJS 是一個用於構建高效、可擴展 Node.js 伺服器端應用程式的進階型 Node.js 框架。它基於 TypeScript 開發，受 Angular 啟發，採用模組化架構和依賴注入（DI）模式。NestJS 提供強大的工具和功能，讓開發者更容易地構建可維護、可測試且高度解耦的複雜應用。

NestJS 的主要特色與優勢

• 模組化架構：透過模組管理程式碼，讓應用結構更清晰、具可維護性。
• 依賴注入：完善且易用的依賴注入系統，大幅提升程式碼的測試性與可維護性。
• TypeScript 支援：發揮 TypeScript 靜態型別檢查、介面及現代 JavaScript 特性的優勢，提高開發效率與程式品質，同時降低執行時錯誤。
• 豐富的裝飾器：使用 Decorators 來定義控制器、服務、模組等，讓程式碼更簡潔、宣告性強且意圖明確。
• 強大的生態圈：NestJS 擁有活躍社群與豐富的外掛/第三方模組，例如 TypeORM、Mongoose、GraphQL、WebSockets、快取、驗證等功能輕鬆集成。
• 標準化構建：構建於成熟的 HTTP 伺服器（Express 或 Fastify）之上，兼容性與效能出色。

有了 NestJS，開發者能遵循後端最佳實踐（如 SOLID 原則、設計模式），快速構建高效能、企業級的 Web 應用、API 服務或微服務架構。

使用 ServBay 建立並運行 NestJS 專案

ServBay 提供 macOS 用戶強大且整合的本地 Web 開發環境，內建多版本 Node.js、常用資料庫與網頁伺服器。本指南帶你利用 ServBay Node.js 環境與「網站」功能，創建、運行及設定一個 NestJS 專案，並透過反向代理功能讓你的本地 NestJS 應用能以自訂網域名稱訪問。

前置條件

開始前，請確保已完成以下準備：

1. 已安裝 ServBay：你已於 macOS 成功安裝 ServBay。
2. 啟用 Node.js 套件：在 ServBay 控制面板「套件」(Packages) 標籤，勾選並安裝所需 Node.js 版本。（如尚未啟用，請參考 ServBay Node.js 使用指南 完成對應設定。）

建立 NestJS 專案

1. 全域安裝 NestJS CLI

   開啟終端機，使用 npm（Node.js 內附）全域安裝 NestJS 命令列工具（CLI）。CLI 是專案初始化、開發與維護的強力利器。

   npm install -g @nestjs/cli

2. 初始化專案

   切換至 ServBay 建議的網站根目錄 /Applications/ServBay/www。這是 ServBay 預設的網站存放路徑，於此新建專案便於後續網站配置。接著用 CLI 創建新專案：

   cd /Applications/ServBay/www
   nest new servbay-nest-app

   執行後，NestJS CLI 會引導你選擇套件管理器（npm、yarn 或 pnpm），建議保持預設選 npm。專案將建立於 /Applications/ServBay/www/servbay-nest-app 資料夾內。

3. 安裝專案依賴

   進入新建專案目錄 servbay-nest-app，並安裝所有所需套件：

   cd servbay-nest-app
   npm install

   nest new 已自動執行 npm install，再次執行可確保依賴完整且最新。

修改 NestJS 專案輸出內容（可選）

為檢查專案運行及能否通過 ServBay 訪問，可修改專案預設路由的回應。

1. 編輯 src/app.controller.ts 檔案

   用熟悉的編輯器開啟專案 src/app.controller.ts，將程式內容改為如下（讓根目錄 / 回應字串 "Hello ServBay!"）：

   import { Controller, Get } from '@nestjs/common';
   import { AppService } from './app.service'; // 假設仍保留 AppService
   
   @Controller()
   export class AppController {
     constructor(private readonly appService: AppService) {} // 若有保留 AppService
   
     @Get()
     getHello(): string {
       // return this.appService.getHello(); // 如使用 AppService
       return 'Hello ServBay!'; // 直接回傳字串
     }
   }

   此段程式定義簡易控制器，處理 HTTP GET 請求至根路徑 (/) 並回傳指定字串。

於開發模式下運行 NestJS 並透過 ServBay 訪問

NestJS 專案通常會於開發模式下使用內建伺服器於特定埠口監聽，並透過 ServBay 的「網站」功能設置反向代理，用自訂網域指向 NestJS 運作中的埠口。

1. 啟動開發伺服器

   至專案目錄 /Applications/ServBay/www/servbay-nest-app，透過下方指令啟動 NestJS 開發伺服器，並設定監聽的埠口，例如 8585：

   cd /Applications/ServBay/www/servbay-nest-app
   PORT=8585 npm run start:dev

   npm run start:dev 會以 ts-node 運行 TypeScript 原始碼，並自動監控檔案異動、即時重啟。伺服器啟動後，將於 localhost:8585 監聽。

2. 設置 ServBay 網站反向代理

   打開 ServBay 控制面板，切至「網站」(Websites) 分頁。點選新增（通常顯示 + 號）建立新網站設定：

   • 名稱 (Name)：自訂網站識別名稱，如 My first NestJS dev site。
   • 網域 (Domains)：輸入欲在本地訪問該專案用的網域，例如 servbay-nest-test.dev。ServBay 預設會將 .dev 等頂級網域解析到本地，無需修改 hosts 檔案。
   • 型態 (Type)：選擇 反向代理 (Reverse Proxy)。
   • IP 位址 (IP Address)：填入 Node.js 監聽 IP，通常為 127.0.0.1（本機迴路）。
   • 埠口 (Port)：輸入 NestJS 運行的埠口，此例為 8585。

   設定完成後請儲存，ServBay 會自動刷新其網頁伺服器（Caddy 或 Nginx）設定。更多詳細步驟請參見 ServBay 添加網站文檔。

3. 瀏覽開發網站

   於瀏覽器訪問你剛設定的網域，例如 https://servbay-nest-test.dev。

   注意：

   • ServBay 會自動給本地網站簽發免費 SSL 憑證（由 ServBay User CA 簽發），因此你可直接用 https 安全連線；若瀏覽器出現憑證警告，需信任 ServBay User CA，詳見 使用 SSL 保護網站文檔。
   • 請確認 NestJS 開發伺服器（PORT=8585 npm run start:dev）已運行，否則無法成功訪問網域。

發佈生產版本並透過 ServBay 訪問

將 NestJS 應用部署至生產環境（即使是本機模擬）時，需先構建專案至生產模式。

1. 構建生產版本

   於專案根目錄 /Applications/ServBay/www/servbay-nest-app 執行下列指令進行編譯建構：

   cd /Applications/ServBay/www/servbay-nest-app
   npm run build

   npm run build 會用 TypeScript 編譯器將原始程式碼轉譯至 dist 目錄。

2. 啟動生產伺服器

   編譯完成後，使用 node 執行編譯後的 JavaScript。舉例指定埠口 8586 且設置 NODE_ENV=production：

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

   生產模式預設不啟用自動監控與熱重載。

3. 設置 ServBay 網站反向代理

   回到 ServBay「網站」標籤，新增或編輯網站設定供生產版本訪問：

   • 名稱 (Name)：如 My first NestJS production site。
   • 網域 (Domains)：如 servbay-nest-test.prod。
   • 型態 (Type)：反向代理 (Reverse Proxy)。
   • IP 位址 (IP Address)：127.0.0.1。
   • 埠口 (Port)：8586（需與生產伺服器一致）。

   完成後儲存。

4. 瀏覽生產網站

   開啟瀏覽器，前往 https://servbay-nest-test.prod 看見生產環境下的 NestJS 應用，亦享有 ServBay SSL 加密。

連線 ServBay 內建資料庫

ServBay 內建多種資料庫系統，包括 MariaDB（相容 MySQL）、PostgreSQL、MongoDB 和 Redis，開發 NestJS 時可輕鬆連線並應用。

重要提醒： 在連線資料庫前請先於 ServBay 控制面板「套件」啟用對應資料庫套件。預設帳號、密碼與埠口，可於 ServBay 控制面板或相關文件查詢。實際生產環境強烈建議更改預設密碼並建立專屬使用者帳號。

以下為 NestJS 常見 ORM / 資料庫庫連線 ServBay 內建資料庫的配置範例。程式一般放於核心模組（AppModule）或獨立資料庫模組內。

1. 連接 MongoDB

   使用 @nestjs/mongoose 套件連接 MongoDB，先安裝所需套件：

   npm install @nestjs/mongoose mongoose

   然後於 NestJS 模組設定 MongooseModule：

   import { Module } from '@nestjs/common';
   import { MongooseModule } from '@nestjs/mongoose';
   // ... 其他 import
   
   @Module({
     imports: [
       MongooseModule.forRoot('mongodb://localhost:27017/servbay-nest-app'), // 預設埠口 27017
       // ... 其他模組
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   ServBay 預設 MongoDB 連線字串為 mongodb://localhost:27017/。你也可透過 MongoDB Compass 或 mongosh 先於 localhost:27017 建立 servbay-nest-app 資料庫。

2. 連接 Redis

   透過 @nestjs/redis 套件連線 Redis，請先安裝套件：

   npm install @nestjs/redis redis @types/redis

   然後於模組內設定 RedisModule：

   import { Module } from '@nestjs/common';
   import { RedisModule } from '@nestjs/redis';
   // ... 其他 import
   
   @Module({
     imports: [
       RedisModule.forRoot({
         url: 'redis://localhost:6379', // 預設埠口 6379
       }),
       // ... 其他模組
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   ServBay Redis 預設地址為 localhost:6379。

3. 連接 MariaDB（MySQL 相容）

   透過 @nestjs/typeorm 套件連接 MariaDB。ServBay 支援 MariaDB 與 MySQL 套件（兩者協議相容），TypeORM 可用 mysql 或 mariadb 皆可。請先安裝下列套件：

   npm install @nestjs/typeorm mysql2 typeorm

   在 NestJS 模組設定 TypeOrmModule：

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   // ... 其他 import
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         type: 'mariadb', // 或 'mysql'
         host: 'localhost',
         port: 3306, // 預設埠口 3306
         username: 'root', // ServBay MariaDB/MySQL 預設 root 帳號
         password: 'password', // 預設 root 密碼
         database: 'servbay_nest_app', // 請事先建立此資料庫
         entities: [], // 輸入你的實體類
         synchronize: true, // 開發建議 true，生產勿用
       }),
       // ... 其他模組
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   注意： ServBay MariaDB/MySQL 預設 root 密碼為 password。請用資料庫客戶端（如 TablePlus、DBeaver 或 MySQL CLI）連到 localhost:3306，使用 root/password 登入並建立 servbay_nest_app 資料庫。為資安考量，請盡快改密碼並建立權限最小化的專用用戶。

4. 連接 PostgreSQL

   使用 @nestjs/typeorm 連接 PostgreSQL。安裝所需套件：

   npm install @nestjs/typeorm pg typeorm

   於模組設定 TypeORM：

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   // ... 其他 import
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         type: 'postgres',
         host: 'localhost',
         port: 5432, // 預設埠口 5432
         username: 'servbay', // ServBay PostgreSQL 預設用戶，請實際確認
         password: 'password', // 預設密碼，請實際確認
         database: 'servbay_nest_app', // 請事先建立此資料庫
         entities: [], // 輸入你的實體類
         synchronize: true, // 開發建議 true，生產勿用
       }),
       // ... 其他模組
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   注意： ServBay PostgreSQL 預設帳號密碼依版本可能為 servbay 或 postgres。請於 ServBay 控制面板或文檔查詢預設憑證，並用 PostgreSQL 客戶端連連 localhost:5432 建立 servbay_nest_app 資料庫與專屬帳號。生產環境務必更改預設密碼！

小結

透過本教學，你已學會如何在 macOS 的 ServBay 本機環境下，快速建立、運行並訪問 NestJS 專案。善用 ServBay 整合的 Node.js、彈性的網站管理（反向代理功能），以及多款內建資料庫，能大幅提升 NestJS 本地開發與測試的效率。你可輕鬆切換開發/生產環境、以自訂網域及 HTTPS 安全訪問你的本地應用，同時也能方便即時串聯 ServBay 強大的資料庫服務。