Docker 部署網站失敗：我如何找出 opencc-js 缺少依賴的問題

更新網站前，我先完成備份

最近我替自己的網站增加「普通文章模式」，希望原創文章可以在同一頁連續顯示圖片和文字，不再使用圖集原本的上一頁、下一頁功能。

程式修改完成後，我把更新包傳到 VPS。這次更新不只涉及前端頁面，也新增了資料庫欄位，所以我沒有立即覆蓋網站，而是先備份原始碼和資料庫。

原始碼備份大約是 312MB，資料庫備份大約是 4.7MB。確認兩個備份檔案都存在後，我才解壓更新包並執行資料庫升級。

接著，我使用 Docker Compose 重新建立網站。原本以為幾分鐘後就能完成，沒想到前端打包時突然出現錯誤：

```

Rollup failed to resolve import "opencc-js"

from AdminGalleryEdit.tsx

```

最後建置程式以 exit code 1 結束。

一開始看到終端出現大量英文訊息時，我以為資料庫升級失敗，或者新程式已經破壞網站。後來仔細檢視才發現，真正重要的是最早出現的錯誤：程式引用了 opencc-js，但專案沒有安裝這個套件。

為什麼建置失敗，舊網站卻仍能開啟？

這次讓我學到一件事：Docker 建置失敗，不一定代表正在執行的網站會立刻停止。

因為新的映像檔沒有成功建立，Docker 沒有用失敗的新版本取代原本的容器。我檢查容器狀態時，舊網站仍然顯示正在執行，MySQL 也保持正常。

這讓我有時間慢慢排查，不需要在網站完全離線的壓力下不斷嘗試指令。不過，這不代表每次部署失敗都一定安全。對我來說，這次最重要的保護就是部署前已經完成程式和資料庫備份。

找到缺少的 opencc-js 依賴

我檢查出錯的後臺文章編輯檔案，發現裡面新增了以下引用：

```

import OpenCC from "opencc-js"

```

這個套件用於處理中文轉換。問題是更新程式時加入了引用，卻沒有同步更新 package.json 和 pnpm-lock.yaml。

Docker 安裝依賴時並不知道需要下載 opencc-js。等到 Vite 和 Rollup 開始打包前端，才發現找不到這個模組。

我先檢查專案使用的套件管理版本，確認是 pnpm 10.4.1。接著利用臨時的 Node 容器補上缺少的依賴，避免直接改動正在執行的網站容器。

完成後，依賴清單顯示：

```

opencc-js 1.4.1

```

這次錯誤不是 Docker 本身損壞，也不是資料庫故障，而是更新包少帶了一項必要的程式依賴。

這也提醒我，以後只要程式加入新的第三方套件，就必須同時檢查 package.json 和鎖定檔是否已經更新。否則即使程式碼本身沒有寫錯，換到另一臺電腦或 Docker 環境後仍然可能無法建置。

重新建置並檢查網站

補好依賴後，我再次執行 Docker Compose 建置命令。

這次前端順利完成打包，Docker 成功建立新的網站映像檔。完成後，容器狀態顯示：

```

MySQL：Healthy

網站：Started

```

看到 Started 以後，我沒有立即結束操作，而是繼續檢查網站容器的狀態和最近日誌。

日誌最後顯示網站服務已經在 3000 連線埠正常執行，容器也沒有持續重新啟動。這代表新的程式不只成功完成建置，也已經由 Docker 正常啟動。

這次經驗讓我明白，部署網站不能只看建置命令有沒有完成。完整檢查至少應該包括：

1. 網站容器是否顯示正在執行。
2. 資料庫容器是否保持健康。
3. 最近日誌是否出現持續重複的錯誤。
4. 實際網站能否正常開啟。
5. 新功能和舊功能是否仍然正常。

如果只看到映像檔建置成功就停止，很可能會忽略容器啟動後才出現的問題。

驗證舊網址與新網址

這次更新也把原本的數字文章網址改成固定英文網址。

舊網址是：

```

/article/01

```

新的固定網址是：

```

/article/onedrive-project-storage-transfer

```

我使用 HTTP 標頭檢查兩個網址。舊網址返回：

```

301 Moved Permanently

```

並自動跳轉到新的固定網址；新網址則返回：

```

200 OK

```

這代表原本分享出去的舊連結仍然可以使用，同時搜尋引擎和讀者會被帶到正確的新網址。

固定網址可以避免發布新文章後，舊的數字編號指向不同內容。對搜尋引擎收錄、社群分享和網站長期管理來說，都比會改變的數字網址穩定。

這次部署讓我學到的事情

經過這次實際操作，我整理出幾個以後會繼續遵守的做法：

1. 修改和部署前先確認正確的專案路徑。
2. 更新前同時備份網站程式和資料庫。
3. 新增套件時，同步更新 package.json 和鎖定檔。
4. 建置失敗時，先找最早出現的錯誤。
5. 不要因為終端出現大量訊息就隨意重複命令。
6. 新容器啟動後，繼續檢查容器狀態和網站日誌。
7. 最後使用實際網址確認跳轉和頁面內容。

以前看到大量錯誤訊息時，我通常會擔心自己把網站弄壞。這次完整處理後，我開始明白：先保留備份、確認舊服務狀態，再逐步找出第一個真正的錯誤，通常比不斷重試更有效。

這不是一項很複雜的技術研究，但對我這種一邊學習、一邊維護自己網站的人來說，是一次很實際的經驗。