Yii2 學習筆記：從零開始安裝高級模板與 Composer 坑點避雷指南

前言：為什麼選擇 Yii2 高級模板？

早年接觸過 Yii 1.x，雖然只知皮毛，但對其結構尚有印象。最近利用業餘時間系統學習 Yii2，目標是構建一套後台管理系統。本文記錄安裝高級模板的完整流程，以及在 Windows 環境下踩過的坑與解決方案，供後續查閱。

學習資源推薦

• 官方權威指南：中文版章節較少、更新滯後，建議英文好的開發者直接閱讀英文版，內容最新、最全。
• 視頻教程：慕課網「與 Yii 框架不得不說的故事」系列，講解深入淺出，極適合入門。
• 搜索引擎：Yii 為國外框架，中文資源有限，善用 Google（配合 XX-Net 等工具）能解決 90% 以上的問題。

核心安裝步驟

1. 熟悉 Composer 倉庫

在 Packagist 搜索 yiisoft/yii2-app-advanced 即可找到高級模板包，頁面右上角可跳轉 GitHub 查看詳細安裝說明。

2. 配置 Composer 中國鏡像

受網絡限制，直接使用官方源極慢甚至失敗。截至 2024 年，推薦使用 Composer 中國全量鏡像（如 https://mirrors.aliyun.com/composer/），按官方文檔配置 config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 即可大幅提速。

Windows 環境常見錯誤與修復

錯誤一：Fatal error: Call to undefined method Fxp\Composer\AssetPlugin\Package\Version\VersionParser::parseLinks

原因：fxp/composer-asset-plugin 版本衝突。
解決：刪除 ~/.composer/vendor/fxp 目錄（Windows 為 %USERPROFILE%\AppData\Roaming\Composer\vendor\fxp），再重新執行安裝命令。參考 GitHub Issue #9794。

錯誤二：Git 認證與命令識別問題

• 需輸入 GitHub Token：在 GitHub Settings → Developer settings → Personal access tokens 生成 token（勾選 repo 權限），按提示輸入即可。
• 'git' 不是內部或外部命令：安裝 Git for Windows 並勾選「Add to PATH」，或手動將 git.exe 所在目錄加入系統環境變量。

錯誤三：資源發布失敗 Invalid Parameter – yii\base\InvalidParamException The file or directory to be published does not exist: .../vendor/bower/jquery/dist

根因：composer global require "fxp/composer-asset-plugin:~1.1.1" 版本號錯誤導致 Bower 包安裝路徑異常。
方案一（推薦）：修正版本號後執行三連擊：
composer self-update && composer global update && composer update
方案二（臨時）：將 vendor/bower/bower-asset/jquery 複製到 vendor/bower/jquery，但可能引發潛在副作用，不建議長期使用。

總結

雖然安裝過程曲折，但通過實踐掌握 Composer 依賴管理、Asset Plugin 機制、跨平台環境差異等核心知識，收穫遠超「一鍵安裝」。後續遇到問題，優先查閱官方 Guide、GitHub Issues、StackOverflow，養成「先搜索、再提問」的習慣，效率事半功倍。

💡 小貼士：現在 Yii2 官方已推薦使用 yiisoft/yii2-app-basic 或通過 composer create-project 直接創建項目，高級模板適合前後端分離、多應用場景，按需選擇即可。