環境設定

本指南將協助你設定 AppFuse 專案的開發環境。

:::note Windows 使用者本指南以 macOS / Linux 為主。Windows 使用者請透過 WSL (Windows Subsystem for Linux) 進行開發。 :::

系統需求

必要工具

工具	版本	用途
Node.js	22.19.0	前端開發與建置
Java	25	後端開發
Git	最新版	版本控制

資料庫

環境	資料庫	說明
開發環境	H2（預設）	嵌入式資料庫，無需安裝，開箱即用
生產環境	MySQL 8.x / SQL Server 2012+ / PostgreSQL 8.2+	依需求選擇

版本管理工具

工具	用途	說明
Volta	Node.js 版本管理	專案已配置 `volta` 設定，自動切換版本
SDKMAN	Java 版本管理	專案已配置 `.sdkmanrc`，自動切換版本

工具	用途
VS Code	IDE（專案已內建工作區配置）
Bruno	API 測試（專案已內建規格於 `app-server/bruno/`）
DBeaver	資料庫管理（支援 H2 及各種生產環境資料庫）

安裝步驟

1. 安裝 Node.js

使用 Volta（推薦）：

Volta 會自動讀取專案中的 package.json 設定，確保使用正確的 Node.js 版本。

# 安裝 Volta
curl https://get.volta.sh | bash

# 設定 shell 環境變數
echo >> ~/.zshrc
echo "# Added by Volta" >> ~/.zshrc
echo "export VOLTA_HOME=\$HOME/.volta" >> ~/.zshrc
echo 'export PATH="$VOLTA_HOME/bin:$PATH"' >> ~/.zshrc

# 重新載入 shell 設定
source ~/.zshrc

# 驗證 Volta 安裝
volta --version

# Volta 會在進入專案目錄時自動安裝並使用正確版本
cd app-office
node --version  # 應顯示 v22.19.0

專案配置（app-office/package.json）：

{
  "volta": {
    "node": "22.19.0"
  }
}

Volta 與 nvm 的差異：Volta 會自動根據專案配置切換版本，無需手動 nvm use。

2. 安裝 Java

使用 SDKMAN（推薦）：

SDKMAN 會自動讀取專案中的 .sdkmanrc 設定，確保使用正確的 Java 版本。

# 安裝 SDKMAN
curl -s "https://get.sdkman.io" | bash

# 重新載入 shell 設定
source ~/.bashrc  # 或 source ~/.zshrc

# 啟用自動切換功能（重要！）
sdk config
# 設定 sdkman_auto_env=true

# 驗證 SDKMAN 安裝
sdk version

# SDKMAN 會在進入專案目錄時自動使用正確版本
cd app-server
java -version  # 應顯示 openjdk version "25.0.1"

專案配置（app-server/.sdkmanrc）：

java=25.0.1-tem

Gradle toolchain 配置（build.gradle.kts）：

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

3. 安裝 Git

# macOS
xcode-select --install

# Linux（Debian/Ubuntu）
sudo apt install git

專案設定

專案透過 /scaffold-project 建立骨架，再以 /scaffold-module 逐步加入模組。以下假設專案名稱為 myapp。

1. Clone 專案

git clone <your-repo-url>
cd myapp/modules

專案結構（依已加入的模組而異）：

myapp/modules/
├── myapp-office-mockup/  # 前端 Prototype
├── myapp-docs/        # 專案文檔站
├── myapp-office/         # 前端生產實作
├── myapp-server/      # 後端生產實作
├── project.json       # 專案配置
└── myapp.code-workspace

2. 後端設定

APP_HOME — 應用程式根目錄

AppFuse 框架將應用程式的運行時資料（設定檔、資料庫、日誌）與程式碼分離，統一存放在 APP_HOME 目錄下。這使得同一份程式碼可以透過不同的 APP_HOME 設定，在不同環境中運行而不需修改原始碼。

$APP_HOME/
├── conf/          # 外部設定檔（覆蓋 classpath 預設值）
├── var/data/      # 資料目錄（如 H2 資料庫檔案）
├── var/logs/      # 日誌目錄
├── var/cache/     # 快取目錄
└── var/tmp/       # 暫存目錄

框架依以下優先順序解析 APP_HOME：

優先順序	來源	設定方式
1	`APP_HOME` 環境變數	`export APP_HOME=/path`（覆蓋 gradle.properties 預設值）
2	`app.home` 系統屬性	`gradle.properties` 中的 `org.gradle.jvmargs=-Dapp.home=~/Project/myapp`
3	預設值	使用者家目錄（`$HOME`）

開發環境：專案的 gradle.properties 已設定預設值 ~/Project/myapp（Environ 會自動展開 ~），通常不需要額外調整。如需使用不同路徑，設定 APP_HOME 環境變數即可覆蓋。

cd myapp-server

# 建置專案
./gradlew clean build

# 啟動應用程式
./gradlew bootRun

預設資料庫：使用 H2 嵌入式資料庫，Hibernate 會自動建立 Schema（ddl-auto: update），無需手動遷移。

後端應該會在 http://localhost:8080/myapp-server 啟動。

驗證：訪問 http://localhost:8080/myapp-server/actuator/health

3. 前端設定

myapp-office-mockup（Prototype）的設定方式相同，將下方的 myapp-office 替換為 myapp-office-mockup 即可。

cd myapp-office

# 安裝依賴
npm install

# 啟動開發伺服器（使用 Mock API）
npm run dev

前端應該會在 http://localhost:3000 啟動。

Mock API：開發環境預設使用 MSW（Mock Service Worker）模擬後端 API，無需啟動後端即可開發前端。

IDE 設定

VS Code 工作區（推薦）

專案提供完整的 VS Code 工作區配置，可同時開發前後端：

開啟工作區：File → Open Workspace from File → 選擇 modules/myapp.code-workspace
安裝推薦擴充功能：VS Code 會自動提示安裝各模組推薦的擴充功能

後端開發擴充功能（myapp-server/.vscode/extensions.json）：

Extension Pack for Java
Gradle for Java
Spring Boot Extension Pack
Kotlin Language
SonarLint

前端開發擴充功能（myapp-office/.vscode/extensions.json）：

ESLint
Prettier
Tailwind CSS IntelliSense

啟動與除錯

後端：在 VS Code 側邊欄的「Spring Boot Dashboard」點擊後端模組啟動

前端：在終端機執行 npm run dev

驗證環境

執行以下命令確認環境正確：

# 版本管理工具
volta --version   # 應顯示 Volta 版本
sdk version       # 應顯示 SDKMAN 版本

# Node.js 版本（在前端模組目錄中）
cd myapp-office
node --version    # v22.19.0

# Java 版本（在後端模組目錄中）
cd myapp-server
java -version     # openjdk version "25.0.1" (Temurin)

# Git 版本
git --version     # git version 2.x.x

注意：Node.js 和 Java 版本會根據專案目錄自動切換，請確保在正確的目錄中執行驗證。

常見問題

H2 Console 存取

開發環境可透過 H2 Console 檢視資料庫（路徑依專案的 application.yml 設定而異）：

URL：http://localhost:8080/myapp-server/h2-console
JDBC URL、Username、Password：參見後端模組的 application.yml 設定

切換至生產環境資料庫

在 $APP_HOME/conf/myapp-server.yml 覆蓋資料庫設定：

spring:
  datasource:
    # MySQL 8.x
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://<host>:<port>/<database>?useUnicode=true&characterEncoding=UTF-8&useSSL=false

    # SQL Server 2012+
    # driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
    # url: jdbc:sqlserver://<host>:<port>;databaseName=<database>;...

    # PostgreSQL 8.2+
    # driver-class-name: org.postgresql.Driver
    # url: jdbc:postgresql://<host>:<port>/<database>

AppFuse 框架會自動載入 $APP_HOME/conf/{app-name}.yml，用於覆蓋 classpath 中的預設設定，無需修改原始碼內的設定檔。

Gradle 建置失敗

錯誤：Could not resolve toolchain

解決：Gradle toolchain 會自動下載 JDK 25，確保網路連線正常

# 清除 Gradle 快取並重新建置
./gradlew clean build --refresh-dependencies

SDKMAN 未自動切換版本

現象：進入專案目錄後 Java 版本沒有自動切換

解決：啟用 SDKMAN 自動切換功能

# 編輯 SDKMAN 設定
sdk config
# 或直接編輯設定檔
vim ~/.sdkman/etc/config

# 設定 sdkman_auto_env=true
# 重新開啟終端機

npm install 失敗

錯誤：網路相關錯誤

解決：

# 清除 npm 快取
npm cache clean --force

# 重新安裝
rm -rf node_modules package-lock.json
npm install

下一步

環境設定完成後：

本地運行 - 在本地啟動專案
開發流程 - 了解日常開發流程
系統架構 - 了解系統整體架構

系統需求​

必要工具​

資料庫​

版本管理工具​

推薦工具​

安裝步驟​

1. 安裝 Node.js​

2. 安裝 Java​

3. 安裝 Git​

專案設定​

1. Clone 專案​

2. 後端設定​

APP_HOME — 應用程式根目錄​

3. 前端設定​

IDE 設定​

VS Code 工作區（推薦）​

啟動與除錯​

驗證環境​

常見問題​

H2 Console 存取​

切換至生產環境資料庫​

Gradle 建置失敗​

SDKMAN 未自動切換版本​

npm install 失敗​

下一步​