在 macOS 上使用 ServBay 進行 ASP.NET Framework 4.x 開發

ServBay 內建強大的 Mono 環境，讓您在 macOS 上能輕鬆且高效地進行 ASP.NET Framework 1.1/2.0/3.x/4.x（最高支援至 4.7.x）開發與測試。

自 ServBay v1.12.0 版本起，我們已整合 Mono 6.14.0，並內含 XSP 開發伺服器以及 fastcgi-mono-server 工具，為您提供兩種主要方式來運行 ASP.NET Framework 4.x 應用：

使用 XSP 進行快速開發與測試： XSP 是專為 Mono 設計、輕量級的 ASP.NET 網頁伺服器，十分適合開發及快速測試階段。
使用 Nginx + FastCGI 部署： 這種模式更穩定、效能更佳，且更貼近生產環境。透過 ServBay 管理的 Nginx，將請求轉發至 Mono 後端進程。

本文將引導您在 ServBay 環境下設定並運行 ASP.NET Framework 4.x 專案。

關於 .NET Framework 與 .NET

請注意，本文著重於基於 Mono 的 ASP.NET Framework 4.x 開發，這是較舊的 .NET 技術堆疊。

ServBay 同時也完整支援最新的 .NET（含 .NET Core、.NET 5/6/7/8+）的開發與部署。若您開發全新 .NET 專案，或考慮遷移到較現代的 .NET 版本，建議選用 ServBay 所提供以官方 Microsoft .NET SDK/執行時為基礎的部署方案，而非本文件內針對 Mono 的 ASP.NET Framework 方法。

前置條件

安裝 ServBay： 請確認您已在 macOS 上安裝 ServBay v1.12.0 或更新版本。
安裝 Mono：
- 開啟 ServBay 應用程式。
- 至左側導覽列選擇「套件」。
- 在套件列表中，找到「.NET」分類並展開。
- 找到「Mono 6」（版本需為 6.14.0 或更高），點擊右側「安裝」按鈕，並等待安裝完成。

準備您的 ASP.NET 專案

專案檔案： 請確保您已經有一個 ASP.NET Framework 4.x 的 Web Application 或 Web Site 專案，並包含 web.config 配置檔案。
推薦存放位置： 我們強烈建議將您的網站專案存放於 ServBay 統一管理的 www 目錄，即 /Applications/ServBay/www/，並為每個專案建立獨立子資料夾。
- 範例： 若您的專案為 MyWebApp，推薦的網站根目錄為 /Applications/ServBay/www/MyWebApp。
- 在後續步驟中，均以 /Applications/ServBay/www/MyWebApp 作為範例，請記得換成您專案的實際路徑。

方法一：使用 XSP（內建開發伺服器）

XSP 是 Mono 隨附的輕量級網頁伺服器，非常適合於本地端 ASP.NET Framework 應用的開發與快速測試。ServBay 內建的 Mono 6 已包含 XSP4（對應 ASP.NET 4.x）。

提示

若您需啟動 ASP.NET 1.1 專案，請使用 xsp 指令。
若需運行 ASP.NET 2.0/3.x 專案，請採用 xsp2 指令。
若運行 ASP.NET 4.x 專案，請使用 xsp4 指令。

操作步驟：

開啟終端機： 啟動 macOS 的終端機（Terminal）。
切換至專案目錄： 使用 cd 指令進入 ASP.NET 專案的根目錄（即包含 web.config 的資料夾）。
bash
```
# 範例：進入名為 MyWebApp 的專案目錄
cd /Applications/ServBay/www/MyWebApp
```
1
2
啟動 XSP 伺服器： 在專案根目錄執行以下指令，啟動 XSP4 伺服器。可指定尚未被占用的埠號（例如 8080、9000），避免和 ServBay 其他服務衝突。
bash
```
# 以 9000 埠啟動目前目錄下的專案
xsp4 --port 9000
```
1
2
- xsp4：調用適用於 .NET Framework 4.x 的 XSP 伺服器。
- --port 9000：指定伺服器監聽的 TCP 埠號。
存取應用程式： 開啟瀏覽器，輸入 http://localhost:9000 或 http://127.0.0.1:9000，您將看見 ASP.NET 應用成功執行於本地端。
停止伺服器： 開發或測試結束後，切回啟動 XSP 的終端視窗，按下 Ctrl + C 或「Enter 鍵」即可停止伺服器。

優點：

設定容易、啟動快速。
十分適合本地開發與除錯。

缺點：

效能不及 Nginx 等正式環境網頁伺服器。
功能較基礎，無法完全模擬生產環境。
需持續開啟終端視窗。

方法二：使用 Nginx + FastCGI

此方法利用 ServBay 管理的 Nginx 作為前端網頁伺服器，負責收取用戶端請求及靜態檔處理，同步透過 FastCGI 傳遞動態請求（如 .aspx、.ashx 等）至 Mono 後端進程（fastcgi-mono-server4）。本方式更貼近生產環境，效能更佳，亦可充分發揮 Nginx 進階功能（如 SSL、快取、壓縮等）。

提示

若需運行 ASP.NET 1.1 專案，請採用 fastcgi-mono-server 指令。
如為 ASP.NET 2.0/3.x 專案，請用 fastcgi-mono-server2 指令。
若為 ASP.NET 4.x 專案，請用 fastcgi-mono-server4 指令。

操作步驟：

確認已安裝、啟動 Mono 與 Nginx：
- 於 ServBay 的「套件」頁安裝 Mono 6 與 Nginx。
- 在「服務」分頁中，確保 Nginx 服務已啟動。
準備 ASP.NET 專案： 建議將專案存於如 /Applications/ServBay/www/MyWebApp 的推薦路徑。
啟動 FastCGI Mono Server：
- 開啟一個新的終端視窗。
- 執行 fastcgi-mono-server4 進程，負責監聽 Nginx 傳來的 FastCGI 請求，解析 ASP.NET 頁面與執行商業邏輯。
  bash
```
# 範例：為 MyWebApp 啟動 FastCGI 服務
fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                     --socket=tcp:127.0.0.1:9001 \
                     --loglevels=Standard \
                     --printlog
```
  1
  2
  3
  4
  5
  - fastcgi-mono-server4：啟動對應 .NET Framework 4.x 的 FastCGI 伺服器。
  - --applications=/:/Applications/ServBay/www/MyWebApp：定義 URL 與實體目錄對應。/: 代表網站根目錄，/Applications/ServBay/www/MyWebApp 為實體路徑。當 Nginx 轉送 /some/page.aspx 時，Mono 會於 /Applications/ServBay/www/MyWebApp/some/page.aspx 找到並執行。請務必更換成您的專案實際路徑。
  - --socket=tcp:127.0.0.1:9001：指定 FastCGI 伺服器監聽之 TCP 位址與埠號。127.0.0.1 表本機、9001 為埠號。請確認此埠未被其它服務或應用程式佔用，並與後續 Nginx 配置中的 fastcgi_pass 一致。
  - --loglevels=Standard --printlog：（可選）於終端即時打印日志，利於除錯與觀察 Mono 輸出。
- 注意： 啟動 fastcgi-mono-server4 的終端視窗須保持開啟，否則服務會中斷。若需長期運行，可透過 nohup、screen 或 tmux 等工具讓進程於背景持續執行。

設定 Nginx 網站：

於 ServBay 介面切至「站點」區段。
點擊「新增站點」或編輯現有站點。
設置網域名稱： 如 mywebapp.servbay.demo。ServBay 會自動寫入 hosts 指向 127.0.0.1。
設定網站根目錄： 非常重要！ 必須對應您的 ASP.NET 專案路徑，例如 /Applications/ServBay/www/MyWebApp，此設定會影響 Nginx 的 root 指令。

啟用並編輯自定義設定： 勾選自定義設定框，ServBay 會產生基礎 Nginx 設定，需根據需要編修以將動態請求轉發至 FastCGI Mono Server。

需檢查／新增的參考設定摘錄如下：

nginx

server {
    listen 80; # 監聽 HTTP 埠
    listen 443 ssl http2; # 監聽 HTTPS，開啟 SSL 與 HTTP/2

    # ServBay 自動管理之 SSL 憑證配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers on;
    ssl_session_timeout 1d;
    ssl_session_cache shared:ServBay:10m;
    ssl_session_tickets off;

    # 憑證檔路徑由 ServBay 自動管理
    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt;
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key;

    server_name mywebapp.servbay.demo; # 應與設定網域一致
    root /Applications/ServBay/www/MyWebApp; # **必須**與網站根目錄一致

    # 新增 ASP.NET 預設首頁，Nginx 找不到 index.html/.htm 時會嘗試以下檔案
    index index.html index.htm default.aspx Default.aspx;

    # 請求處理主要邏輯
    location / {
        # 按序尋找檔案 ($uri) 或資料夾 ($uri/)
        # 若找不到靜態檔，則交由 @mono 處理
        try_files $uri $uri/ @mono;
    }

    # （可選但建議）Nginx 直接高效處理一般靜態文件
    # 可透過 expires 利用瀏覽器快取
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max; # 最大化瀏覽器快取期限
        log_not_found off; # 不記錄找不到靜態文件錯誤
        access_log off; # 不記錄靜態檔存取日志，減少磁碟Io
    }

    # 定義 @mono，處理動態請求
    location @mono {
        # 將請求經由 FastCGI 傳給 Mono Server
        # **埠號必須**與 fastcgi-mono-server4 啟動用參數一致
        fastcgi_pass 127.0.0.1:9001;

        # 引入基本 FastCGI 參數
        include fastcgi_params;
        # 關鍵參數：設置腳本檔名，Mono Server 依此尋找並執行 ASP.NET 檔案
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # PATH_INFO 通常不用，故設為空
        fastcgi_param PATH_INFO "";

        # （視需求補充）其它 FastCGI 參數
        # fastcgi_param HOST $host;
    }

    # ServBay 也可能自動加入其他預設，如日志路徑等
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

儲存設置並重載／重啟 Nginx： ServBay 介面完成設定儲存後，會自動嘗試重載 Nginx。若語法有誤會彈出提示訊息。如有需要，也可於「服務」手動重啟 Nginx。

存取應用程式： 開啟瀏覽器，造訪您設於 Nginx 的網域（如 https://mywebapp.servbay.demo）。因已配置 443 埠 SSL，建議使用 HTTPS。Nginx 會直接傳回靜態檔案，將動態請求轉送給 fastcgi-mono-server4，由 Mono 負責執行 ASP.NET 程式碼。

優點：

效能佳、穩定，極適合貼近正式環境的測試。
可善用 Nginx 諸如靜態檔案服務、SSL、負載平衡等多項功能。
與 ServBay 的網站與網域統一管理深度整合。

缺點：

配置相較 XSP 稍繁瑣。
需手動管理 fastcgi-mono-server4 進程（除非利用進程管理工具）。

如何選擇最合適的方式

快速開發、除錯與簡易功能測試 — 請選擇 XSP，它最即時便利，單一指令即可執行。
若需高效能，或貼近正式環境的功能與內部佈署測試，而且欲善加利用 Nginx 進階特性（如 HTTPS、自定義網域、靜態優化）與 ServBay 的網站管理，則建議採用 Nginx + FastCGI。

注意事項與疑難排解

檔案權限： 請確保 Nginx 執行用戶（一般由 ServBay 管理）以及啟動 fastcgi-mono-server4 的 macOS 用戶都擁有對專案目錄（如 /Applications/ServBay/www/YourProjectName）之讀取與執行權限。必要時可用 chmod 或 chown 修正權限。
路徑一致性： 務必確認 Nginx 配置（root 指令）和 fastcgi-mono-server4 指令（--applications 參數）的專案底下路徑正確，且皆指向含 web.config 的根目錄。
埠號衝突： 確認 XSP 或 fastcgi-mono-server4 使用之埠號（如 9000、9001）未被 ServBay 其他服務或你系統中其他程序占用。
日誌檢查：
- 請留意 fastcgi-mono-server4 啟動時終端機日誌。加上 --printlog 能隨時監控 Mono 執行時狀態。
- 至 Nginx 錯誤日誌排查問題。ServBay 會於站點設置顯示路徑，多位於 /Applications/ServBay/logs/nginx/your-domain.error.log。錯誤日誌有助於診斷 Nginx 配置或與 FastCGI Mono 的連結問題。
Mono 版本相容性： ServBay 內建的 Mono 6.14.0 約略相容 .NET Framework 1.1~4.7.2。若專案用到更高版本特性，或出現相容問題，請考慮利用 ServBay 安裝微軟官方 .NET SDK/執行時跑現代 .NET 程式，或調整專案 Framework 版本。
FastCGI 進程管理： 若選擇 Nginx + FastCGI，請切記 fastcgi-mono-server4 需持續執行。開發階段可直接用終端運作，較正式情境則需設為背景服務或搭配進程管理器。

利用 ServBay 內建的 Mono 6 環境與推薦專案結構，讓您能在 macOS 上更規範且流暢地開發、運行傳統 ASP.NET Framework 4.x 應用程式。祝您開發之路順利！

在 macOS 上使用 ServBay 進行 ASP.NET Framework 4.x 開發 ​

前置條件 ​

準備您的 ASP.NET 專案 ​

方法一：使用 XSP（內建開發伺服器） ​

方法二：使用 Nginx + FastCGI ​

如何選擇最合適的方式 ​

注意事項與疑難排解 ​