跳至主要内容

建構指南

本文件說明如何建構 AppFuse 應用系統的部署檔案。

建構產出物​

模組建構工具產出物說明
app-serverGradleapp-server.war後端 WAR 檔案
app-webnpm + Vitedist/ 目錄前端靜態檔案
app-web-hostGradleapp-web-host.war前端托管層 WAR（封裝 dist/）

重要：生產環境部署需要 app-server.war + app-web-host.war，前端不直接使用 dist/。

建構環境需求​

後端建構環境​

軟體版本說明
JDK25+編譯與執行
Gradle8.x由 Gradle Wrapper 提供

前端建構環境​

軟體版本說明
Node.js22.xJavaScript 執行環境
npm10.x套件管理工具

後端建構（app-server）​

建構 WAR 檔案​

cd app-server

# 清理並建構
./gradlew clean war

# 驗證產出
ls -la build/libs/
# app-server.war

建構選項​

# 跳過測試（加速建構）
./gradlew war -x test

# 指定環境配置
./gradlew war -Pprofile=prod

# 顯示詳細建構資訊
./gradlew war --info

檢查依賴​

# 查看依賴樹
./gradlew dependencies

# 查看特定配置的依賴
./gradlew dependencies --configuration runtimeClasspath

前端建構（app-web）​

安裝依賴​

cd app-web

# 安裝所有依賴
npm install

# 或使用 ci（CI/CD 環境建議）
npm ci

建構生產版本​

# 建構
npm run build

# 驗證產出
ls -la dist/

環境配置​

前端配置採用「程式碼預設值 + 後端覆蓋」機制，而非建置時環境變數：

// src/conf/config.ts - 程式碼預設值
export const config: AppEnvironConfig = {
  app: {
    name: 'App',
    baseURL: '/',  // API 基礎路徑
    msw: {
      enabled: import.meta.env.DEV,  // 開發環境啟用 Mock
    },
  },
}

生產環境可透過後端 /config endpoint 覆蓋配置：

// GET /config 回應（可選）
{
  "app": {
    "baseURL": "/api/v1"
  }
}

指定環境建構：

# 使用 production 環境（預設）
npm run build

# 明確指定模式
npm run build -- --mode production

建構產出結構​

dist/
├── index.html
├── assets/
│   ├── index-[hash].js
│   ├── index-[hash].css
│   └── ...
└── favicon.ico

前端托管層建構（app-web-host）​

app-web-host 將前端靜態檔案封裝成 WAR，提供：

  • SPA 路由轉發
  • CSP nonce 注入
  • 安全 Headers 配置（HSTS、CSP 等）
  • 動態 base href 注入

建構步驟​

# 1. 確保 app-web 已建構
cd app-web
npm run build

# 2. 建構 app-web-host（會自動複製 dist/）
cd ../app-web-host
./gradlew build

# 驗證產出
ls -la build/libs/
# app-web-host.war

完整建構流程​

建構腳本範例​

建立 build.sh：

#!/bin/bash
set -e

echo "=== AppFuse 建構腳本 ==="
echo "時間: $(date)"

# 後端建構
echo ""
echo ">>> 建構後端 (app-server)..."
cd app-server
./gradlew clean war -x test
echo "後端建構完成: build/libs/app-server.war"

# 前端建構
echo ""
echo ">>> 建構前端 (app-web)..."
cd ../app-web
npm ci
npm run build
echo "前端建構完成: dist/"

# 前端托管層建構
echo ""
echo ">>> 建構前端托管層 (app-web-host)..."
cd ../app-web-host
./gradlew clean build
echo "前端托管層建構完成: build/libs/app-web-host.war"

echo ""
echo "=== 建構完成 ==="
echo "產出物："
echo "  - app-server/build/libs/app-server.war"
echo "  - app-web-host/build/libs/app-web-host.war"

執行建構​

chmod +x build.sh
./build.sh

安裝媒體準備​

建構完成後，準備以下安裝媒體：

deployment-package/
├── app-server.war              # 後端 WAR 檔案
├── app-web-host.war            # 前端托管層 WAR 檔案
├── conf/
│   └── application.properties  # 配置檔範本
└── README.txt                  # 安裝說明

打包腳本範例​

#!/bin/bash
VERSION=${1:-$(date +%Y%m%d)}
PACKAGE_DIR="appfuse-$VERSION"

mkdir -p $PACKAGE_DIR/conf

# 複製 WAR 檔案
cp app-server/build/libs/app-server.war $PACKAGE_DIR/
cp app-web-host/build/libs/app-web-host.war $PACKAGE_DIR/
cp app-server/src/main/resources/application.properties $PACKAGE_DIR/conf/

# 建立壓縮檔
tar -czf $PACKAGE_DIR.tar.gz $PACKAGE_DIR

echo "安裝包已建立: $PACKAGE_DIR.tar.gz"

建構問題排解​

問題：Gradle 建構失敗​

# 清理 Gradle 快取
./gradlew clean
rm -rf ~/.gradle/caches/

# 重新建構
./gradlew war --refresh-dependencies

問題：npm 安裝失敗​

# 清理 npm 快取
npm cache clean --force
rm -rf node_modules package-lock.json

# 重新安裝
npm install

問題：記憶體不足​

# 增加 Gradle 記憶體
export GRADLE_OPTS="-Xmx2048m"
./gradlew war

# 增加 Node.js 記憶體
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

下一步​

建構完成後，請參閱 安裝指南 進行系統部署。