Astro 新手部署全攻略：避免常見設定錯誤與踩雷指南#

錯誤現象#

• Build 過程中出現警告或錯誤
• 部署成功，但網頁行為異常或無法啟動
• 第三方套件報錯或不兼容

為什麼會出現#

Astro 官方文檔會建議使用特定 Node 版本，但：

• 本地開發環境可能版本過舊或過新
• CI/CD 預設 Node 環境與本地不同
• 第三方套件可能需要特定版本支持

解決方案（Step by Step）#

1
# 確認本地 Node 版本
2
node -v
3

4
# 安裝官方建議版本
5
nvm install 20
6
nvm use 20
7

8
# 確認 Deno 版本（如使用）
9
deno --version

在 package.json 明確指定 Node 版本：

1
"engines": {
2
  "node": ">=20"
3
}

延伸問題#

• Node 版本過舊會導致部分套件編譯失敗
• CI/CD pipeline 未同步版本，可能 build 成功，但部署失敗

實務建議#

• 在 CI/CD workflow 中固定 Node 版本
• 每篇文章或專案都記錄使用的 Node/Deno 版本

錯誤現象#

• 部署後 CSS / JS 無法載入
• 圖片路徑錯誤，頁面顯示破圖
• 在本地正常，但部署到 Cloudflare Pages 失敗

為什麼會出現#

• Astro 預設靜態資源路徑為根目錄 /
• 部署到子路徑或 CDN 時，未設定 base
• 相對路徑使用不當

解決方案（Step by Step）#

1
export default defineConfig({
2
  base: '/你的路徑/'
3
});

或使用相對路徑：

1
<link rel="stylesheet" href="./styles/main.css">
2
<script src="./scripts/app.js"></script>

延伸問題#

• 多環境部署（本地 / Preview / Production）路徑不一致
• 瀏覽器快取導致資源載入舊版本

實務建議#

• 部署前先本地 build 測試
• 對不同環境設置環境變數管理 base path

錯誤現象#

• Workflow 跑通，但 deploy 失敗
• 權限錯誤、Token 不存在
• 專案預覽成功，但正式部署失敗

為什麼會出現#

• 直接 fork 官方 workflow，未設定環境變數或 Secret
• branch 指向錯誤或 target 不正確
• token 過期或權限不足

解決方案（Step by Step）#

1
env:
2
  CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

• 確保 Secret 設定正確
• workflow branch 對應 main / production
• 驗證 token 是否具有必要權限

延伸問題#

• 部署到不同環境需要不同 token
• Workflow 設計不合理可能 silent fail

實務建議#

• 每篇文章或專案都註明 token / secret 用途
• CI/CD log 必須檢查部署成功訊息

錯誤現象#

• 部署成功，但功能不完整
  • Functions 路徑錯誤
  • Edge config 未正確設定
• 預覽正常，正式部署失敗

為什麼會出現#

• 新手依官方快速 start，忽略 production 設定
• Edge function 或 environment variable 未正確設置

解決方案（Step by Step）#

1. 檢查 functions 路徑，確保 Cloudflare Pages 可識別
2. 確認 Edge config 對應環境變數
3. 本地測試 production build
4. 部署前檢查 log

延伸問題#

• 多地區部署差異
• 不同 Node 版本兼容性問題

實務建議#

• 建立不同環境的設定檔
• 每次部署前先做本地 build

錯誤現象#

• 新文章沒連到舊文章
• 相同主題散落，Google 難以理解主題權威

解決方案#

• 每篇文章至少連 2 篇舊文章
• 舊文章補連到新文章
• 使用長尾關鍵字作 anchor text，例如：
  • Astro 部署到 Cloudflare Pages
  • GitHub Actions workflow 配置錯誤

實務建議#

• 強制每篇文章檢查內部連結
• 建立站內「主題樹狀圖」，方便後續文章拓展