如何建立不會影響正式環境的重構環境？

前一章已經分析遺留系統的功能、資料變化與相依關係。接下來要建立獨立的重構工作環境，讓開發人員可以重現問題、修改程式，並且驗證目標系統的實作結果。

直接在正式環境修改程式，可能中斷現行功能、改變正式資料，或觸發無法立即復原的外部影響。只保留唯一一份程式碼也有類似風險：修改前後缺少可比較的基準，失敗時難以回到已知可執行的狀態。安全的重構環境需要同時做到以下三件事：

1. 與正式環境的設定、資料及外部互動隔離。
2. 記錄啟動系統所需的程式版本、相依項目與操作順序。
3. 能從已知初始狀態重複啟動，並且用固定案例驗證關鍵功能。

先定義與正式環境的隔離邊界

使用不同目錄只能隔離程式檔案。如果重構環境仍然載入正式設定、連接正式資料來源，或把結果送往正式使用的外部項目，執行測試時仍可能影響現行運作。建立環境前，應該逐項決定替代方式與阻擋條件。

啟動步驟也應該主動檢查這些邊界。例如，環境名稱未設定、目的地不在允許清單，或設定內容含有已知的正式環境識別時，就停止啟動。這種檢查可以在設定放錯位置時提早阻止後續影響。

如果目前只能取得正式環境中的資料，應該先確認可以取用的範圍，再建立受控副本並移除不必要的敏感內容。重構環境不應該因為設定方便而長期依賴正式資料來源。

用 Git 保留可比較的程式基準

Git 可以記錄程式碼的版本與修改歷程。開始修改前，先保存一個已知可建置或可啟動的版本，再從這個基準建立重構用分支。每次修改維持明確範圍，後續就能比較行為差異，也能找出哪一項變更造成問題。

版本控制仍需要配合下列做法：

• 將建置方式、相依項目清單、設定範本與啟動腳本納入版本控制。
• 將本機設定、執行結果、暫存內容與未加密的敏感資訊排除在版本控制之外。
• 在提交前檢查變更內容，確認沒有密鑰、密碼、權杖（Token）或正式環境的連接資訊。
• 為設定範本提供欄位名稱與範例值，不填入可以直接使用的正式內容。

.gitignore 只會讓尚未納入追蹤的檔案維持未追蹤狀態，無法自動移除已經提交的內容。如果敏感資訊曾經進入 Git 歷程，刪除目前檔案中的文字仍不足以解除風險，需要立即停用或更換該資訊，再按照專案規範處理既有歷程。

記錄系統啟動所需的條件

遺留系統常依賴特定版本、預設路徑或未寫入文件的啟動順序。只複製程式碼，可能得到可以閱讀卻無法執行的副本。建立環境時，至少需要確認下列內容：

無法確認版本時，不要直接改用最新版本。可以先從目前仍能執行的環境、建置檔、套件鎖定檔與執行紀錄取得資訊，再逐項測試可以接受的版本範圍。推斷的內容與已確認的內容應該分開記錄，避免把暫時可用的組合誤認為必要條件。

將設定與敏感資訊移出程式碼

不同環境通常需要不同的資料位置、功能開關與外部目的地。這些差異應該由環境設定提供，程式碼只定義需要哪些欄位及如何讀取，不直接寫入正式值。

一般設定可以保存在設定範本，實際值則透過未納入版本控制的設定檔、環境變數（Environment Variable）或既有設定管理機制，在啟動時提供。設定值不得輸出到執行紀錄；錯誤訊息也應該只顯示缺少哪個欄位，不顯示欄位內容。

密鑰、密碼與權杖等敏感資訊需要另外管理。工具選擇應該配合既有環境、需要管理的範圍與維護能力，不需要為單一重構環境強制增加集中式工具。常見選項如下：

不論採用哪一種方式，重構環境都應該使用專用且可停用的敏感資訊。即使取得正式環境的敏感資訊，也不應該複製到重構環境繼續使用。

選擇能重複建立的環境方式

重構環境可以使用安裝腳本、虛擬機器（Virtual Machine, VM）、容器（Container）或開發容器（Development Container, Dev Container）建立。選擇方式取決於系統對作業系統、安裝流程及外部項目的依賴程度。

開發容器規格可以將開發工具與設定寫入 devcontainer.json，讓支援該規格的工具建立一致的開發環境。容器本身則可以透過映像檔與啟動設定描述程式所需的相依項目。系統如果依賴無法放入容器的作業系統行為，可以改用虛擬機器，或將兩者組合使用。

環境形式不同，隔離原則不會改變。映像檔、虛擬機器範本或啟動腳本都不能包含正式環境的敏感資訊，也不能把正式目的地設為預設值。

建立單一且可重複執行的啟動方式

環境可以在原開發人員的工作目錄啟動，不代表其他人也能重現。應該提供一份從乾淨初始狀態開始的操作文件，並且盡量將固定步驟寫成腳本。內容至少包含：

1. 檢查必要工具、版本及環境設定是否齊全。
2. 取得指定版本的程式碼與相依項目。
3. 建立重構環境專用設定，並且檢查隔離邊界。
4. 按照固定順序啟動系統與必要的相依項目。
5. 建立測試資料或載入固定的初始內容。
6. 執行基本確認與關鍵功能驗證。
7. 停止系統，並且清除或重設產生的內容。

啟動腳本應該在缺少必要條件時停止並說明原因，不要略過錯誤後繼續執行。重複執行前，也需要能清除前一次留下的狀態，或判斷現有狀態是否符合預期。如此才能區分程式問題與環境殘留造成的差異。

文件完成後，應該從新的工作目錄重新執行一次，並請未參與環境建立的人按照文件操作。過程中需要人工補充、臨時修改或憑記憶完成的步驟，都應該回寫到文件或腳本。

用固定案例驗證環境與功能

可重現的環境還需要可重複的驗證方式。先選擇少量但能涵蓋主要處理路徑的功能，為每個案例準備固定輸入、必要初始狀態與預期結果。每次重建環境後執行相同案例，確認結果沒有因版本、設定或啟動順序而改變。

驗證時可以按照下列順序檢查：

• 從獨立工作目錄啟動系統，全程不需要讀取或修改正式環境。
• 確認實際載入的程式版本、套件版本與環境名稱符合文件。
• 執行關鍵功能，記錄輸入、輸出、狀態變化與錯誤結果。
• 再次建立相同初始狀態並重複執行，確認結果一致。
• 檢查產生的檔案、通知與後續工作只留在重構環境。
• 停止並重設環境，確認下次執行不依賴前一次留下的內容。

如果兩次結果不同，先比較實際版本、載入設定、初始內容與相依項目，再判斷是否為程式行為差異。這些執行紀錄會成為後續修改與驗收的共同基準。

完成的重構工作環境應該可以回答三個問題：

• 能否在不接觸正式環境的情況下啟動系統？
• 必要的版本、設定與相依項目是否已經記錄？
• 關鍵功能能否從相同初始狀態重複執行並得到可比較的結果？

只要其中一項仍需依靠特定人員的記憶或正式環境，環境就還不能作為穩定的重構基準。

重點整理

• 重構環境需要隔離正式程式、設定、資料、外部互動與產生結果；只使用不同目錄仍不足以避免影響正式環境。
• Git 可以保留可比較的程式基準與修改歷程，但敏感資訊必須移出版本控制；如果內容曾經提交，還需要停用或更換並處理既有歷程。
• 建立環境時需要記錄程式基準、執行環境、相依項目、環境設定、初始內容與操作順序，不能只複製程式碼。
• 設定與程式碼應該分離，密鑰、密碼及權杖可以按照實際需要透過環境專用設定、集中式管理工具或加密設定檔提供。
• 安裝腳本、虛擬機器、容器與開發容器各有適用情況，選擇後仍需遵守相同的隔離與敏感資訊管理原則。
• 單一啟動方式與固定驗證案例讓問題可以重現，也讓目標系統的實作結果能由其他人重複確認。