整體流程 #

1. 準備開發所需的環境
2. 取得原始碼並安裝相依套件
3. 在開發伺服器上確認運作
4. 建立正式環境建置
5. 設定 Nginx 並發布建置完成的檔案
6. HTTPS 支援(視需要而定)
7. 重新啟動時自動啟動(視需要而定)

以下的操作手冊將提供具體的作業範例。

STEP1. 準備開發環境 #

STEP1.1 安裝 Node.js 和 npm #

若使用 Ubuntu,可透過以下指令安裝 Node.js 和 npm。

sudo apt update
sudo apt install -y nodejs npm

安裝後確認版本。

node -v
npm -v

STEP1.2 準備伺服器 #

• 準備 Ubuntu 等 Linux 伺服器,並確保能夠透過 SSH 登入。
• (以正式營運為前提)請準備具有 root 或 sudo 權限的使用者。

STEP2. 取得原始碼 #

STEP2.1 下載/複製原始碼 #

• 若在 GitHub 等平台上,可使用 git clone https://... 取得
• 若為 Zip 檔案,請上傳後解壓縮
• 以下假設原始碼放置於 /home/project。

STEP2.2 安裝相依套件 #

移動至原始碼所在的目錄,並使用 npm install 安裝所需的函式庫。

cd /home/project
npm install

成功後會產生 node_modules 目錄。

STEP3. 在開發伺服器上確認運作 #

開發時使用 npm run dev 在本機啟動簡易伺服器。以下為範例。

npm run dev

執行後終端機會顯示類似 Local: http://localhost:5173 的日誌。
在瀏覽器存取該 URL 即可確認應用程式正在運作。

• 若要在遠端伺服器上測試,請將 vite.config.ts 的 server.host 設定為 0.0.0.0,以允許外部存取。

STEP4. 建立正式環境建置 #

開發完成後,建立正式環境的建置。這會將應用程式最佳化,並在 dist 目錄中
產生最終的靜態檔案(HTML/JS/CSS)。

cd /home/project
npm run build

• 成功後會在專案根目錄產生 dist 資料夾。
• 其中包含 index.html 和 assets 資料夾等內容。

STEP5. 使用 Nginx 發布建置完成的檔案 #

通常不使用 Vite 的預覽伺服器,而是透過 Nginx 等網頁伺服器發布靜態檔案。

STEP5.1 安裝 Nginx #

在 Ubuntu 上安裝 Nginx。

sudo apt update
sudo apt install -y nginx

安裝後,在瀏覽器存取 http://<伺服器的IP位址>/ 即可看到
「Welcome to nginx!」頁面。

STEP5.2 配置正式環境檔案 #

1. 建立發布資料夾(例如: /var/www/myapp)

   sudo mkdir -p /var/www/myapp
   

2. 複製建置完成的檔案(dist內的內容)

   sudo cp -r /home/project/dist/* /var/www/myapp/
   

3. 配置後確認內容

   ls -l /var/www/myapp
   # 若有 index.html 和 assets 資料夾即表示正常
   

STEP5.3 建立 Nginx 設定檔 #

Nginx 的標準做法是在 sites-available/ → sites-enabled/ 管理
server { ... } 區塊的設定檔。

1. 建立新的設定檔

   sudo nano /etc/nginx/sites-available/myapp.conf
   

2. 輸入以下內容(SPA 的設定範例)

   server {
       listen 80;
       server_name _;  # 僅使用 IP 存取時。若使用網域則為 server_name example.com;
       root /var/www/myapp; # dist 檔案配置路徑
       index index.html;
   
       # SPA 對應設定: 即使路由路徑為 /xxx 也會回退至 index.html
       location / {
           try_files $uri $uri/ /index.html;
       }
   }
   

   • server_name 若使用正式網域則例如: server_name example.com;
   • root /var/www/myapp; 指定建置完成檔案的配置目錄
   • try_files $uri $uri/ /index.html; 是為了使用 React Router 等工具時,即使直接輸入 URL 也能回退至 index.html 的設定
3. 啟用設定檔並停用預設設定

   # 建立符號連結將 myapp.conf 放置於 sites-enabled
   sudo ln -s /etc/nginx/sites-available/myapp.conf /etc/nginx/sites-enabled/
   
   # 若有預設網站則將其停用
   sudo rm /etc/nginx/sites-enabled/default
   

4. nginx 設定檔的語法檢查 & 重新載入

   sudo nginx -t
   sudo systemctl reload nginx
   

5. 在瀏覽器中存取 http://<伺服器的IP>/
   • 若顯示建置的應用程式,而非先前的「Welcome to nginx!」,即表示成功。

STEP6. 導入 HTTPS (SSL)(視需要) #

在正式環境中,一般會對應 https://。
使用免費的 Let’s Encrypt (Certbot) 範例:

sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

以互動方式進行後,nginx 會自動整合 SSL 設定,即可以 HTTPS 存取。
(DNS 必須將 yourdomain.com 指向此伺服器)

STEP7. 重新啟動時的自動啟動 #

STEP7.1 僅靜態檔案的情況 #

若 Vite 建置的靜態檔案由 nginx 配送,
只要nginx 已設定自動啟動即可。請確認下列啟用是否完成。

sudo systemctl enable nginx

如此即可在伺服器重新啟動時自動啟動 nginx。

STEP7.2 有 Node.js + Express / API伺服器的情況 #

若需要後端的 Node.js,並在同一伺服器上執行,一般會使用 PM2 或 systemd 將 Node.js 處理程序常駐化。

# 安裝 PM2
sudo npm install -g pm2

# 啟動應用程式(Express等)
pm2 start "npm run start" --name my-backend

# 啟用自動啟動
pm2 startup systemd
pm2 save

nginx 僅將 /api/ 的請求以 proxy_pass 轉送至 Node.js,
前端則以靜態檔案配送的架構。

STEP8. 疑難排解 #

1. 仍顯示「Welcome to nginx!」
   • 未停用預設設定
   • server_name 不符合
2. 出現 404 錯誤
   • root 的設定路徑有誤
   • SPA 未設定 try_files
3. 無法在瀏覽器中存取
   • 未開放連接埠 80/443(雲端的安全群組或 UFW)
   • 伺服器 IP 或網域名稱未正確指派

STEP9. 總結 #

1. 開發: 以 npm run dev 確認運作
2. 建置: npm run build → 產生 dist 資料夾
3. 以 nginx 配送: 將 dist 的內容放置於 /var/www/myapp → 設定 myapp.conf → nginx -t → systemctl reload nginx
4. 對應 HTTPS: 以 certbot --nginx -d yourdomain.com 等取得憑證
5. 自動啟動: 僅靜態檔案使用 nginx,若需自建 API 則以 PM2 或 systemd 常駐管理 Node.js