初探 Java 後端開發：解決 macOS 環境下 Spring Boot 項目啟動的各類「坑」

在 macOS（尤其是 Apple Silicon M1/M2/M3 芯片）環境下進行 Java + Spring Boot + Docker 的聯合開發時，由於系統架構差異與環境配置細節，新手往往會遇到「代碼拉下來卻跑不起來」的窘境。本文將解決過程整理為一份全記錄，涵蓋從環境變量加載到 Docker 跨平台兼容性的核心方案。

🛠 一、 環境變量自動加載：EnvFile 插件配置

Spring Boot 默認不讀取 .env 文件。為了解決本地運行時的環境變量注入，我們使用 EnvFile 插件。

• 操作步驟 ：
  1. 在 IDEA 插件市場安裝 EnvFile。
  2. 在 Edit Configurations... -> EnvFile 標籤頁勾選 Enable EnvFile。
  3. 點擊 + 號導入 docker/hktv_sims/local.env。
• 避坑指南（重要） ：
  • 不要勾選 Executable 複選框。
  • 如果誤勾選，macOS 會嘗試執行該純文本文件，導致報錯：java.io.IOException: error=13, Permission denied。

🐳 二、 Docker 鏡像與跨平台兼容性優化

在 M2 Pro 芯片上運行 Docker 時，最常見的錯誤是 no match for platform in manifest: not found。

• 權宜之計 ：在 Dockerfile 中強行指定 -platform=linux/amd64。
• 團隊最佳實踐（推薦） ：為了不影響 Windows 或 Intel Mac 同事，避免硬編碼 platform 參數 。
  • 優化方案 ：將鏡像標籤從特定的 mysql:8.0.25 改為 mysql:8.0。
  • 原理 ：mysql:8.0 是一個多架構鏡像。Docker 引擎會根據運行環境自動抓取對應版本：M2 Mac 抓取原生 arm64，Windows 抓取 amd64。這不僅解決了報錯，還提升了 M2 Mac 上的運行性能。

🚀 三、 啟動應用前的關鍵指令

重要提醒 ：在 IDEA 中點擊「Run」啟動 Application 之前，必須先啟動數據庫等容器服務。

請在終端執行以下命令：

docker-compose up -d

這會確保你的後端程序在啟動時能夠連接到已經就緒的數據庫。

📂 四、 數據卷掛載導致的啟動崩潰

症狀 ：數據庫容器報錯 chown: cannot dereference '/var/lib/mysql/mysql.sock': No such file or directory。

• 原因分析：這是由於之前的異常關閉或跨平台鏡像切換，在本地掛載目錄中留下了損壞的套接字文件，導致 MySQL 初始化腳本失效。
• 解決方案 ：執行清理命令，刪除本地掛載的數據文件夾（例如 docker_volumes/hktv_sims_db/var/lib/mysql），然後重新執行 docker-compose up -d 即可。

docker-compose down
rm -rf [本地數據目錄路徑]
docker-compose up -d

🔗 五、 定位真實的數據庫訪問端口

症狀 ：後端報 Communications link failure 或 UnknownHostException。

• 原因分析 ：在 macOS 本機開發時，必須通過 localhost 和映射端口訪問容器。
• 操作步驟 ：
  1. 運行 docker ps 查看容器狀態。
  2. 檢查 PORTS 欄位。例如看到 0.0.0.0:3416->3306/tcp。
  3. 同步修改 local.env 中的 DATABASE_HOST=127.0.0.1 與 DATABASE_PORT=3416。

✅ 總結與成果驗證

完成上述優化後，重新運行項目。當你在控制台看到 Started SimsApplication 且 Swagger 文檔初始化成功，說明環境已完美打通。

核心心法：

1. EnvFile 只加載不執行。
2. 鏡像版本 優先選擇多架構標籤。
3. 運行前 務必先執行 docker-compose up -d。
4. 連接端口 永遠以 docker ps 的實時映射結果為準。