安裝與啟動故障排查

如果您在安裝 Minecraft 官方版本、模組載入器（Forge/Fabric/NeoForge/Quilt）、模組、模組包、光影，或是啟動遊戲時遇到任何問題，本指南將一步步協助您定位並解決這些故障。

---

🌐 1. 下載失敗或卡住 (網路連線問題)

故障表現

• 下載 Minecraft 遊戲檔案、資產資源、庫檔案或 Forge/Fabric 等載入器時，下載進度一直卡在 0% 處。
• 啟動器彈出逾時或連線相關的錯誤提示（例如 CONNECTION_TIMED_OUT, NAME_NOT_RESOLVED, HTTP_STATUS 504）。

解決方案

使用下載源鏡像

如果 Mojang 官方伺服器或 Mod 載入器官方伺服器在您的地區網路延遲過高，或者被您的網路服務提供商攔截，您可以切換到替代的公益鏡像源：

1. 點擊左側邊欄底部的 設定 按鈕（齒輪圖示）。
2. 滾動頁面到 網路設定 區域。
3. 找到 下載源 / 鏡像（Download Source / Mirror）選項。
4. 將該設定從 預設 修改為 BMCLAPI 或 MCBBS（這兩個鏡像源每日與官方數據保持高速同步）。

代理伺服器設定

如果您的網路存取特定服務受到限制，您可以在啟動器內直接配置網路代理：

1. 前往 設定 -> 網路設定，找到代理伺服器配置區域。
2. 填寫您的 SOCKS5 或 HTTP 代理伺服器地址。
3. 測試代理連線是否正常。

---

📦 2. 模組或模組包部分檔案下載失敗 (CurseForge 第三方下載限制)

故障表現

• 下載模組包（Modpack）或單個模組時，部分檔案下載失敗並顯示帶有警告標識。
• 提示“限制第三方啟動器下載”（Restricted third-party downloads）。

問題原因

CurseForge 平台上的部分模組作者關閉了第三方 API 的下載權限，強制要求玩家必須訪問其官方網頁來下載模組以獲取廣告收益。

解決方案

XMCL 智能集成了手動補全機制，您可以非常方便地補齊這些缺失的檔案：

1. 在啟動器右上角打開任務管理器，查看下載失敗的詳細任務。
2. 點擊失敗模組旁邊的下載連結，這會在您的預設瀏覽器中打開該模組的 CurseForge 網頁。
3. 在網頁中手動將該 .jar 模組檔案下載到您的本地電腦。
4. 將瀏覽器下載好的 .jar 檔案直接 拖拽（Drag-and-Drop） 到 XMCL 啟動器窗口中（或手動將其放入當前實例的 mods 資料夾中）。
5. XMCL 會自動檢測並匹配該檔案，隨後自動繼續並完成其餘的安裝流程。

---

🔍 3. 模組在 CurseForge 網站上有，但在啟動器內搜尋不到

故障表現

• 在啟動器內搜尋某個模組時，提示“未找到結果”，但該模組明明能在 CurseForge 官方網站上正常查看。

問題原因

CurseForge 平台允許模組作者禁用第三方 API 訪問權限。一旦作者禁用了該功能，CurseForge 的 API（XMCL 搜尋和獲取模組時所依賴的接口）將無法在搜尋結果中返回該模組。

解決方案

1. 打開您的網頁瀏覽器，訪問 CurseForge 官網模組頁面。
2. 手動點擊 Download，將該模組的 .jar 格式檔案保存到您的電腦上。
3. 打開 XMCL 並選中您當前正在使用的遊戲實例（實例卡片）。
4. 將瀏覽器下載好的 .jar 模組檔案直接拖拽（Drag-and-Drop）到啟動器的主窗口上。XMCL 將會自動識別並安裝到該實例的 mods 資料夾內。

---

📦 4. 匯入的模組包「消失」或模組清單為空

故障表現

• 將模組包的 .zip 或 .mrpack 格式檔案拖拽進啟動器進行匯入後，卻在當前遊戲設定檔中找不到，或者對應的模組清單顯示為空。

問題原因

1. 新實例創建機制：為了防止混亂，XMCL 不會將匯入的模組包內容直接塞進您當前正在運行的舊實例。相反，它會為這個模組包創建一個全新的遊戲實例（實例卡片）。
2. 後台下載任務進行中：模組包本身的壓縮包裡為了節省空間，通常不包含實際的 .jar 模組檔案，只包含模組清單（元數據）。匯入完成後，XMCL 會在後台默默下載清單上的所有模組。在下載完成前，模組清單看起來可能是一片空白。

解決方案

1. 切換遊戲實例：點擊左側的邊欄功能表或實例切換器查看所有的遊戲卡片。找到以該模組包命名的全新卡片並選中它。
2. 檢查任務管理器：點擊啟動器右上角的 任務管理器 圖標（帶有載入圓圈的圖標），檢查模組包的下載任務是否仍在運行。請耐心等待所有下載人員完成後再啟動遊戲。

---

🔄 5. 檔案損壞一直重複下載 (控制校驗和不匹配循環)

故障表現

• 啟動器一直在重複下載某一個庫檔案或資源檔案，並提示檔案損壞。
• 遊戲因為檔案校驗失敗而一直無法正常啟動。

問題原因

由於之前的某次下載被異常中斷，損壞的緩存檔案在本地被佔用鎖死，導致啟動器無法用正確的檔案覆蓋它。

解決方案

1. 在啟動器的診斷資訊或日誌中找到受損檔案的具體路徑（例如 libraries/org/lwjgl/...）。
2. 在實例面板中點擊右上角的 資料夾 圖標，打開當前實例的數據目錄。
3. 按照錯誤提示中的路徑找到對應受損庫檔案所在的整個資料夾並將其徹底刪除。
4. 在啟動器中點擊 修復（Repair）或重新啟動遊戲。啟動器此時會重新下載一個全新、完整的檔案副本。

---

☕ 6. 遊戲啟動後瞬間崩潰或閃退 (Java 版本不相容)

故障表現

• 點擊啟動後，遊戲啟動了但瞬間閃退，並返回錯誤代碼 1 或 -1。
• 遊戲日誌（Log）中出現 UnsupportedClassVersionError 或“未找到 Java”等報錯。

問題原因

不同版本的 Minecraft 對 Java（JDK）版本有著嚴格的要求。使用不匹配的 Java 版本會導致遊戲直接崩潰。

解決方案

XMCL 擁有極其智能的自動 Java 管理器，可以替您一鍵下載並配置相容的 JDK。

Java 版本相容對照表

請確保您的實例配置了正確的 Java 版本：

• Minecraft 1.12.2 及更早版本：Java 8
• Minecraft 1.16 - 1.17：Java 16 / 17
• Minecraft 1.18 - 1.20.4：Java 17
• Minecraft 1.20.5 及更高版本：Java 21

如何在 XMCL 中管理和選擇 Java：

1. 前往實例的設定頁面（啟動按鈕旁邊的齒輪圖示）。
2. 找到 Java 設定區域。
3. 點擊選擇框。XMCL 會列出您系統上檢測到的所有 Java 版本，並用綠色的勾號標記出完全相容的版本。
4. 如果您的系統上沒有合適的 Java 版本，請點擊 安裝 Java，啟動器將自動下載並配置最適合您當前遊戲版本的 JDK。

---

📑 7. 啟動器本身無法打開或出現黑屏

故障表現

• 雙擊啟動器圖標後沒有任何反應。
• 啟動器窗口能打開，但整個界面是一片漆黑。

解決方案

您可以通過查看主日誌檔案來排查導致崩潰具體原因：

1. 訪問您本地的啟動器數據資料夾：
   • Windows：在運行（Win+R）中輸入 %appdata%\xmcl 並回車。
   • macOS：~/Library/Application Support/xmcl
   • Linux：~/.config/xmcl
2. 打開其中的 logs 資料夾，並找到最新的 main.log 檔案。

---

📋 8. 生成診斷報告 (推薦的第一步)

在手動搜尋龐雜的日誌檔案之前，我們強烈建議您先嘗試使用啟動器內置的 生成診斷報告 功能。這會把啟動器日誌、遊戲日誌以及系統運行環境等所有診斷資訊自動打包成一個獨立的檔案，極大地方便了社區和開發者幫您快速查明原因。

如何生成診斷報告：

1. 點擊啟動器頂部導航欄的 幫助與回饋（Help & Feedback）功能表。

2. 點擊 生成報告（Generate Report）按鈕將相關的診斷資訊和日誌打包。

   

---

📑 9. 如何分析啟動器與遊戲日誌

如果您希望手動查找日誌排查問題，日誌檔案能夠準確地還原當時發生的情況。以下是各種日誌的存放路徑及常見崩潰排查指南。

🔍 如何找到日誌檔案

根據是啟動器出錯還是遊戲本身崩潰，您需要去不同的資料夾查找日誌：

A. 啟動器主日誌 (main.log)

適用於啟動器界面崩潰、下載失敗、網路連線錯誤、登入故障等：

• Windows：按下快捷鍵 Win + R，輸入 %appdata%\xmcl\logs 並回車。
• macOS：定位到 ~/Library/Application Support/xmcl/logs 目錄。
• Linux：定位到 ~/.config/xmcl/logs 目錄。
• 在其中找到最新的 main.log 檔案。

B. 遊戲運行日誌 (latest.log 與崩潰報告)

適用於模組衝突、Minecraft 崩潰、卡頓、遊戲內部的 Java 報錯等：

• 在啟動器中打開實例的管理卡片。
• 點擊實例頁面右上角的 資料夾 圖標以打開其遊戲根目錄。
• 前往 logs 資料夾，打開 latest.log 檔案。
• 如果遊戲崩潰閃退，請前往 crash-reports 資料夾，查找最新的 .txt 檔案（命名格式通常為 crash-年-月-日_時.分.秒-client.txt）。

---

🛠 分析日誌並修復常見錯誤

使用任何文字編輯器（例如記事本）打開上述日誌檔案，然後使用搜尋功能（Ctrl + F）來查找特定的異常代碼：

🔴 情況 1：記憶體溢出錯誤 (Out of Memory)

• 特徵字元：java.lang.OutOfMemoryError: Java heap space 或遊戲退出代碼 -805306369。
• 原因：為遊戲分配的執行記憶體（RAM）不足，無法載入當前實例中的所有模組。
• 解決方法：
  1. 進入該實例的設定頁面（啟動按鈕旁的齒輪圖示）。
  2. 向下滾動到 Java 設定區域。
  3. 適當調大 最小記憶體 和 最大記憶體 的值（例如將最大記憶體調整為 4096 或 6144 MB）。

🔴 情況 2：模組衝突或缺失前置庫

• 特徵字元：Mixin transformation failed、DependencyResolutionException，或者出現 Requires mod 'fabric' (version X or later), but only version Y is installed。
• 原因：某些模組運行所需的關聯模組（前置庫依賴）沒有下載，或者兩個模組之間互不相容。
• 解決方法：仔細閱讀那行報錯資訊，通常它會明確列出缺失的前置模組名稱。去官網下載對應的前置模組並放入 mods 資料夾中，或移除/更新衝突的模組版本。

🔴 情況 3：Java 執行環境版本衝突

• 特徵字元：java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime。
• 原因：當前所用的 Java 版本太低，無法支援新版遊戲或模組（例如用 Java 8 啟動 Minecraft 1.20）。
• 解決方法：打開實例設定，在 Java 區域下點擊 安裝 Java 按鈕，啟動器會自動幫您安裝最適合該遊戲版本的 Java 環境。

🔴 情況 4: 顯卡驅動崩潰 / OpenGL 錯誤

• 特徵字元：GLFW error 65542: WGL: The driver does not seem to support OpenGL 或 Pixel format not accelerated。
• 原因：您的電腦顯卡驅動程式丟失、版本過舊，或者遊戲沒有被分配給高性能獨立顯卡，誤用了集成顯卡啟動。
• 解決方法：前往您的顯卡品牌官網（NVIDIA, AMD 或 Intel）下載安裝最新的顯卡驅動。如果是筆記型電腦，請在系統設定中為 Java 程序強制開啟“高性能顯卡驅動”模式。

---

❓ 依然看不懂日誌辦？

如果您仔細看過了日誌但仍不知道崩潰是怎麼回事，請別擔心！XMCL 社區在多個平台提供了熱情的求助板塊：

1. 加入我們官方的 Discord 社區

• 與開發者及眾多玩家直接交流，即時獲取解答。

• 加入連結：Discord 官方伺服器

• 提問方式：前往 #feedback-and-idea 頻道，直接上傳您剛才生成的診斷報告檔案或崩潰 .txt 日誌，切勿在聊天框內複製貼上上千行日誌內容。

• 點擊查看我們反饋求助頻道的版面說明：

  

2. 在 Reddit 社區提問

• 您也可以在我們的海外玩家論壇上發帖詢問：
• 傳送門：r/XMCL Subreddit

3. 在 GitHub 提交 Issue

• 如果您確認所遇問題是啟動器本身的程式 Bug，可以提交 Bug 報告。
• 報告地址：XMCL GitHub Issues 反饋板塊
• 在 Issue 描述中附上您的診斷報告，以便開發人員進行調試排查。