iT邦幫忙

2024 iThome 鐵人賽

DAY 28
0
自我挑戰組

讓我們一起與turboRepo共舞系列 第 28

Turborepo 常見vercel部署問題

  • 分享至 

  • xImage
  •  

以下是文章的繁體中文翻譯與重點整理:

錯誤列表

你在使用 Vercel 平台時,可能會遇到各種錯誤。本節著重於你與 Vercel 儀表板互動時可能發生的錯誤。

  1. 缺少 public 目錄
    當輸出目錄丟失、空白或無效時,建置步驟會失敗。解決方法:

    • 確認專案設定中輸出目錄正確。
    • 檢查建置命令或根目錄。
    • 嘗試在本地執行建置命令,確認檔案正確生成。
  2. 缺少建置腳本
    這與使用 Vercel CLI 16.7.3 或更早版本有關,若專案缺少 api 目錄及 vercel.json 檔案,需要提供建置腳本以靜態生成前端並輸出至 public 目錄。

  3. 團隊成員請求數量上限
    最多允許 10 個加入團隊的請求,超過請求數時需由團隊擁有者批准或拒絕現有請求。

  4. Git 帳號權限錯誤
    若部署失敗並顯示「需要團隊訪問」,則提交者的 Git 帳號未連接至團隊,需將 Git 帳號連接到對應的 Vercel 團隊。

  5. 封鎖範圍
    若違反公平使用或服務條款,Vercel 可能會封鎖團隊,導致無法進行新部署或邀請新成員。

  6. 無效路由規則
    路由的 source 屬性應使用 path-to-regexp 語法,而不是正則表達式。

  7. 建置器依賴安裝失敗
    在運行 vercel buildvercel dev 時,如果 npm 安裝失敗,可能是因為 npm 未安裝、網路連線中斷,或建置器未發佈至 npm registry。

  8. 衝突的配置檔案
    同時存在 vercel.jsonnow.json 會導致錯誤,解決方法是刪除 now.json

  9. 不支援的 Next.js 函數配置
    使用 Next.js 時,只有 memorymaxDuration 可以配置,其他設定由 Next.js 自動處理。

  10. 無法重新部署生產環境
    若已有更新版本的部署,則無法重新部署舊的生產部署。若需覆蓋,請選擇「Promote」功能。

以下是未完成部分的繁體中文翻譯與重點整理:

  1. 無法載入專案設定
    如果 .vercel 檔案中的專案設定屬於你不屬於的團隊,部署時會出錯。解決方法:
  • 刪除 .vercel 目錄並重新部署以重新連結專案。
  • 在 macOS 或 Linux 中執行以下指令:
    rm -rf .vercel
    vercel
    
    在 Windows 中執行:
    rmdir /s /q .vercel
    vercel
    
  1. 專案名稱驗證
    專案名稱僅允許最多 100 個字母、數字的小寫字符,中間可用連字號,但不能以連字號開頭或結尾。

  2. 倉庫連結限制
    根據你的方案,Vercel 專案可以連結的 Git 倉庫數量有限。若達到上限,需先解除現有連結,再連結新的專案。

  3. 透過 CLI 進行域名驗證
    透過設定 Vercel 的名稱伺服器或 DNS 記錄,來將域名指向 Vercel。你可以使用指令 vercel domains inspect <domain> 來檢查域名狀態。

  4. 離開團隊
    若你是團隊的最後一個擁有者或確認成員,你無法離開團隊。若要離開,請先將擁有者角色轉交給其他成員,或刪除整個團隊。

  5. Git 預設忽略列表
    使用 Vercel CLI 進行部署時,系統會自動忽略一些檔案,這些檔案在 Git 中則需手動忽略。若意外提交了這些檔案,可用以下指令移除:

git rm file.txt
echo 'file.txt' >> .gitignore
git add .gitignore
git commit -m "Removed file.txt"
git push
  1. 找不到 GitHub 應用程式安裝
    當 Vercel 無法從 GitHub 檢索應用程式安裝資訊時,可能會出現連結錯誤。嘗試等待幾分鐘重新連接,如果問題仍存在,請聯絡 GitHub 支援。

  2. 預覽分支用作生產分支
    若將自定義 Git 分支配置為預覽分支,它將被視為預覽環境的分支。要將此分支用作生產分支,需先清空該分支的域名與環境變數設定,再將其分配為生產分支。

  3. 失去 Git 倉庫訪問權限
    Vercel 必須與 Git 倉庫連結以進行部署。若 Git 倉庫被刪除、存檔,或移除 Vercel 應用程式,會中斷連結。檢查 GitHub 應用程式的訪問權限,確保 Vercel 有權訪問對應的倉庫。

  4. SSL 憑證刪除被拒絕
    由 Vercel 平台管理的 SSL 憑證(如測試域名的萬用 SSL 憑證)無法手動刪除。企業方案的自定義 SSL 憑證則允許手動刪除。

  5. 生產分支用作預覽分支
    生產分支設定為提供給訪客的代碼,若要將特定 Git 分支配置為預覽分支,則需手動輸入該分支,並且不可與生產分支相同。

  6. vercel dev 命令找不到
    vercel dev 嘗試調用本機機器上不存在的子程序時,會出現「命令未找到」錯誤。需要安裝對應的程序,如 Go 函數需安裝 Go 二進制文件。

  7. 遞迴命令調用
    若專案的建置或開發命令中調用了 vercel buildvercel dev,會導致遞迴錯誤。解決方法是調整命令,不要直接調用 vercel buildvercel dev,而應使用框架提供的建置命令。

  8. 不支援的 pnpm 引擎
    package.json#engines.pnpm 版本與目前運行的 pnpm 版本不匹配,將出現 ERR_PNPM_UNSUPPORTED_ENGINE 錯誤。解決方法:

  • 設置環境變數 ENABLE_EXPERIMENTAL_COREPACK=1,並確認 packageManager 值正確。
  • 或從 package.json 中移除 engines.pnpm 值。
  1. 無效的 Edge Config 連接字串
    若環境變數中包含過時的 Edge Config 連接字串,部署將失敗。解決方法是更新或刪除包含舊連接字串的環境變數。

  2. 全域安裝的 @vercel/speed-insights 或 @vercel/analytics
    若這些套件在系統全域安裝但未在 package.json 中引用,部署會失敗。解決方法是在 package.json 中將這些套件加入為依賴項。

  3. 超大增量靜態重建(ISR)頁面
    如果 ISR 回應超過 20 MB,生產環境將無法渲染,並返回 FALLBACK_BODY_TOO_LARGE 錯誤。此問題影響 Next.js 的預渲染功能及其他使用預渲染功能的框架。

這些重點總結了 Vercel 錯誤信息的詳細解釋與解決方法,幫助使用者應對各類常見的技術問題。


上一篇
turboRepo快取不能自己做嗎?
下一篇
Turborepo 核心概念整理
系列文
讓我們一起與turboRepo共舞30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言