Grails 專案從 Git 克隆後在本機無法運行的環境配置問題排查

問題現象

• 公司電腦 (STS + Grails 2.2.1) 正常 run-app
• 個人電腦 (同版本環境) 克隆專案後：紅線錯誤、依賴解析失敗、run-app 卡在「Configuring classpath」
• 同事現場修復後複製專案，個人電腦再次出錯

核心原因分析

系統性排查步驟

步驟 1：統一執行環境

# 1. 確認 Java 版本 (Grails 2.2 需 Java 7/8)
java -version
# 建議使用 SDKMAN 管理
sdk install java 8.0.382-tem
sdk install grails 2.2.1

# 2. 設定環境變數 (~/.bashrc 或 ~/.zshrc)
export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java))))
export GRAILS_HOME=$HOME/.sdkman/candidates/grails/current
export PATH=$GRAILS_HOME/bin:$PATH

步驟 2：清理 IDE 專案元資料

# 在專案根目錄執行
rm -rf .settings .classpath .project target/ stacktrace.log
# 保留原始碼與建構腳本
# 重新導入 IDE：File → Import → Existing Gradle/Grails Project

步驟 3：重新解析依賴

# 1. 清理 Grails 快取
grails clean
rm -rf ~/.grails/2.2.1/projects/your-project/

# 2. 強制刷新依賴
grails refresh-dependencies --non-interactive

# 3. 離線模式測試 (若有本地倉庫)
grails --offline run-app

步驟 4：檢查關鍵配置檔案

# BuildConfig.groovy 重點檢查：
grails.project.fork = [run: false]  // 避免 fork 模式導致 classpath 問題

# Config.groovy / DataSource.groovy 中的 import 錯誤：
// 錯誤：import org.springframework.core.io.ClassPathResource
// 原因：缺少 spring-core 依賴或版本衝突
// 解決：在 BuildConfig.groovy dependencies 區塊添加
compile "org.springframework:spring-core:4.3.30.RELEASE"
compile "org.springframework:spring-context:4.3.30.RELEASE"

步驟 5：解決「Configuring classpath」卡住

• 網路問題：Grails 嘗試下載插件元資料，配置代理或使用離線模式
• 插件版本衝突：BuildConfig.groovy 中 plugins 區塊鎖定具體版本
• 記憶體不足：export GRAILS_OPTS="-Xmx2g -Xms1g"

最佳實踐：團隊環境一致性保障

快速修復腳本

#!/bin/bash
# fix-grails-env.sh
echo "=== 清理專案元資料 ==="
rm -rf .settings .classpath .project target/

echo "=== 清理 Grails 快取 ==="
grails clean
rm -rf ~/.grails/$(grails -version | awk '{print $2}')/projects/$(basename $PWD)/

echo "=== 重新解析依賴 ==="
grails refresh-dependencies --non-interactive

echo "=== 嘗試啟動 ==="
grails run-app

總結

Grails 專案跨機器遷移失敗，核心在於 執行環境不一致 (JDK/Grails 版本、環境變數) 與 IDE 元資料污染。建立標準化環境 (SDKMAN + Grails Wrapper)、清理 IDE 專案檔、統一依賴解析流程，是解決此類問題的根本之道。