Android Studio 中直接按 F2 或在專案視圖右鍵「Rename」往往導致引用關係斷裂、Gradle Sync 失敗、R 檔案找不到。正確做法是使用 Refactor → Rename，IDE 會自動掃描全專案引用並同步修改，包含包名、類名、資源 ID、Gradle 配置、Manifest 等。本文演示標準重命名流程與避坑指南。

🎯 為什麼不能用 F2/右鍵 Rename？

• 僅修改文件系統名稱，不更新 Java/Kotlin 代碼中的 import、引用。
• 不修改 build.gradle 中的 applicationId、namespace。
• 不更新 AndroidManifest.xml 中的包名、組件名。
• 導致 R.java 生成錯誤，編譯報錯「Unresolved reference: R」。

✅ 標準 Refactor Rename 流程

步驟 1：選中目標節點

在 Project 視圖（左側）選中要重命名的：模塊、包、類、資源文件、資源目錄 等任意節點。

步驟 2：啟動重構重命名

頂部選單 → Refactor → Rename...（快捷鍵 Shift+F6）。

步驟 3：輸入新名稱並預覽變更

彈出對話框輸入新名稱，勾選：

• Search in comments and strings：同步修改註釋、字符串中的引用（建議開啟）。
• Search for text occurrences：掃描非代碼文本（XML、JSON、README 等）。

點擊 Refactor → 底部 Refactoring Preview 標籤頁展開，逐項確認將被修改的文件與行號。

步驟 4：確認執行

預覽無誤後點擊預覽面板左側 Do Refactor，IDE 執行全專案重命名，過程中會重新索引、Gradle Sync。

🎯 常見重命名場景與注意點

場景	操作節點	關鍵注意事項
修改包名	選中包節點（如 com.example.app）	必須同步修改 build.gradle namespace/applicationId、Manifest package，Refactor 會自動處理
修改模塊名	選中模塊根節點	同步更新 settings.gradle include、目錄名、build.gradle rootProject.name
修改 Activity/Fragment 類名	選中 .kt/.java 文件	自動更新 Manifest 註冊、Layout XML 引用、Intent 調用處
修改資源文件名	選中 res/ 下文件	自動更新 R.id 引用、Layout XML、Java 代碼 R.layout.xxx
修改 drawable/mipmap 目錄名	選中目錄	慎用！建議新建目標目錄遷移文件，避免密度限定符錯亂

🛠️ 進階：配合版本控制

1. 重命名前 Commit 當前狀態（Git: git commit -am "pre-rename"）。
2. 執行 Refactor Rename。
3. 檢查 git diff 確認變更範圍合理。
4. 提交重命名提交（git commit -am "refactor: rename module/app/package to newname"）。

❌ 失敗回滾方案

若重命名後專案無法編譯：

1. git reset --hard HEAD~1 回滾到重命名前。
2. 或使用 IDE 內建 Local History（右鍵文件 → Local History → Show History）還原關鍵文件。
3. 清理緩存：File → Invalidate Caches / Restart → Invalidate and Restart。

掌握 Refactor Rename，告別「改個名、改半天」的痛苦，重構重命名才是專業 Android 開發者的標配技能！