AWS帳號充值優惠 AWS CDK 部署（cdk deploy）報 Synthesis Error 或權限不足診斷

先搞清楚：cdk deploy 到底在哪一段出錯

AWS CDK 的 cdk deploy 看起來像是一個指令，其實背後做了好幾件事：先合成模板，再比對差異，接著把資源送到 CloudFormation，由 CloudFormation 去真正建立或更新資源。很多人一看到錯誤訊息，就直接把它統稱為「部署失敗」，但實際上最常見的兩大類問題，分別是 Synthesis Error 和 權限不足。這兩類錯誤發生的位置不同，排查方法也完全不一樣。

AWS帳號充值優惠 如果你連錯誤在哪一層都沒分清楚，修錯方向通常會走偏。Synthesis Error 代表 CDK 在本地合成模板時就卡住了，還沒真正把模板送去部署；權限不足則多半是模板已經產生，真正進入 AWS 之後，因為 IAM、CloudFormation、S3、ECR 或 KMS 等權限不夠而被拒絕。先分層，後診斷，這是處理 CDK 問題最省時間的原則。

Synthesis Error 是什麼，為什麼常被誤判

所謂 Synthesis Error，簡單說就是 cdk synth 這一步沒過。cdk deploy 內部本來就會先做 synth，所以只要合成階段有問題，部署根本還沒開始。這類錯誤常讓人誤以為是 AWS 權限問題，因為畫面上也可能出現 AWS 相關字樣，但本質上卻是本機環境、程式碼、上下文資料或模板結構出了問題。

最典型的情況有幾種：第一，程式碼本身有錯，例如 TypeScript 編譯失敗、Python 套件缺失、Construct 參數不合法。第二，CDK 需要查詢 AWS 資訊來完成合成，但你的本機沒有正確憑證，或目前的帳號、區域和堆疊設定對不上。第三，資產打包失敗，例如用到 Docker bundling，卻沒有安裝 Docker，或 Docker daemon 沒有啟動。第四，環境上下文缺失，例如 VPC lookup、Hosted Zone lookup、AMI lookup 需要先查詢既有資源，但查詢不到或權限不足，就會在 synth 階段直接中斷。

先看錯誤發生在哪個命令階段

你可以先把錯誤訊息切開看。如果在執行 cdk synth 就已經失敗，幾乎可以確定是 synthesis 階段的問題。如果 cdk synth 能通過，但 cdk deploy 才失敗，那多半是部署權限、CloudFormation 執行權限或資源建立權限不足。這個判斷很重要，因為很多人一開始就去查 IAM，結果花半天才發現是程式碼語法錯誤或 context 沒載入。

建議養成一個習慣：先跑 cdk synth，再跑 cdk deploy。如果 synth 都不過，就先別碰 AWS Console。相反地，如果 synth 正常、deploy 報錯，再去查角色與權限，效率會高很多。

Synthesis Error 的常見原因與排查順序

當你遇到 synthesis error，最有效的做法不是亂改，而是按順序縮小範圍。先看編譯，再看 context，最後看資產與環境。很多問題其實都能在本機就抓出來，不必等到上雲才發現。

1. 程式碼或編譯失敗

AWS帳號充值優惠 如果你使用 TypeScript、Python、Java 或 Go 開發 CDK，首先要排除語言層面的問題。像是 import 路徑錯誤、套件版本不一致、語法錯誤、類型不符，都會讓 synth 直接失敗。這種情況下，錯誤訊息通常很直白，可能是編譯器報錯，也可能是 runtime 例外。

處理方式很直接：先單獨執行專案的 build 或 test 指令，再跑 cdk synth。不要把 build 問題混進 deploy 問題裡。很多團隊把 CDK 和應用程式碼放在一起，結果 package lock 或虛擬環境壞掉，最後看起來像 CDK 問題，其實只是依賴沒有安裝完整。

2. Context lookup 失敗

AWS帳號充值優惠 CDK 很常在 synth 階段去查現有資源，例如 VPC、Subnet、Hosted Zone、AMI。這些查詢需要 AWS 憑證，而且查詢結果會被寫進 cdk.context.json。如果你換了帳號、換了區域，或本機沒有權限查詢，就會出現 synthesis error。

這類錯誤常見的特徵是訊息中出現 lookup、context、needs to perform AWS calls 之類字眼。診斷方法通常有三步：先執行 aws sts get-caller-identity 確認目前使用的是哪個帳號與角色；再檢查 CDK App 中的 env 是否明確指定 account 與 region；最後查看 cdk.context.json 是否卡住舊資料。必要時可以刪除該檔案重新合成，但前提是你知道自己在重建哪些查詢結果。

3. Docker 或資產打包問題

如果你的 CDK 專案有 bundling、asset、DockerImageFunction、Lambda 層或某些自訂打包流程，synth 可能會呼叫 Docker。這時候即使 AWS 權限完全沒問題，也可能因為本機沒有 Docker、Docker 沒啟動、檔案權限不足或映像檔無法拉取而失敗。

這類問題的解法通常不是改 IAM，而是先確保本機可正常執行 Docker 指令。你可以單獨測試容器執行是否正常，再回頭執行 cdk synth。若專案使用私有映像，還要確認登入狀態與映像倉庫授權。

AWS帳號充值優惠 4. 堆疊定義不合法

有些 synthesis error 來自 CloudFormation 模板本身不合法，例如資源名稱格式錯誤、依賴關係不完整、參數過長、輸入值不符合 schema。CDK 會盡量幫你擋掉很多問題，但不是所有錯誤都能在編譯期發現。當你看到模板生成失敗，或某個 Construct 無法被轉成資源時，就要回到相對應的屬性設定去檢查。

這裡最常見的習慣性錯誤，是把 AWS 資源名稱、ARN、路徑、Tag 值寫錯格式，或者在不該使用 token 的地方硬塞字串拼接。CDK 很強大，但它不是替你吞下所有不合法輸入的保險箱。

權限不足通常不是一種錯，而是一整組錯

如果 synth 已經通過，真正部署時才失敗，那就是另一個世界。這時候問題往往不是「沒權限」四個字可以解釋完的，而是你到底缺的是哪一段流程的權限。CDK 部署時可能涉及的角色很多：本機使用者憑證、部署用的 IAM 角色、CloudFormation 執行角色、bootstrap 建立的資源角色、資產上傳用的 S3 或 ECR 權限，甚至還有 KMS 加解密權限。

很多人以為只要有 AdministratorAccess 就一定沒事，但實務上仍可能失敗，因為部署流程中有些角色是交由 CloudFormation 代替執行，真正擁有權限的不是你目前登入的那個使用者。也有情況是你能建立堆疊，但不能修改某個既有資源，或者能上傳模板，卻不能把 Lambda 資產推到 ECR。

1. 本機登入身份有問題

先確認目前 CLI 用的是誰。執行 aws sts get-caller-identity，看回傳的 Account、Arn、UserId 是否符合預期。很多事故都只是因為本機切到了錯的 profile，或 SSO token 過期。當你明明以為自己是管理員，實際上只是另一個測試角色，部署當然會被拒絕。

如果你使用 AWS SSO，記得確認登入是否過期。若是 CI 環境，要檢查臨時憑證是否還在有效期內。這種問題通常不是程式碼錯，而是身份認證已經失效。

2. 缺少 CloudFormation 與資源建立權限

部署時最常見的權限不足，會出現在 CloudFormation 嘗試建立資源的那一刻。例如你可以呼叫 cloudformation:CreateStack，但無法建立 IAM Role、S3 Bucket、EC2 Security Group、Lambda Function 或 DynamoDB Table。CDK 對這些資源的操作，最後都會落到 CloudFormation 的執行權限上。

如果錯誤訊息中出現 is not authorized to perform、AccessDenied、not authorized to execute，就應該往 IAM 的方向查。不要只盯著你登入的那個 principal，還要看 CloudFormation stack execution role 是否有對應的權限。尤其是建立 IAM 相關資源時，常需要 iam:CreateRole、iam:PassRole、iam:AttachRolePolicy、iam:PutRolePolicy 等權限。

3. Bootstrap 資源或執行角色不足

CDK 部署依賴 bootstrap 堆疊。bootstrap 沒做好，或做得不完整，也很容易造成權限錯誤。常見現象是資產無法上傳、模板無法存取、角色無法 assume，或 CDK 需要的查詢角色不存在。這種問題表面上像是部署失敗，實際上是基礎設施準備不足。

如果你是在新帳號或新區域部署，第一件事應該是確認 bootstrap 是否已完成，且版本足夠。很多老帳號只做過舊版 bootstrap，面對新版 CDK 的資產流與角色結構，會出現各種奇怪的權限錯誤。這時候不是改應用程式碼，而是先補齊基礎環境。

4. S3、ECR、KMS 權限被卡住

CDK 在部署 Lambda、Docker image、asset 或加密資源時，常常會碰到 S3、ECR、KMS。最常見的例子是：模板上傳到 bootstrap bucket 時被拒絕，Docker image 推送到 ECR 時被拒絕，或使用客製 KMS key 時無法加解密。這些權限往往不在你的第一直覺裡，但卻是部署成功的關鍵。

如果你看到錯誤訊息提到 s3:PutObject、ecr:BatchCheckLayerAvailability、kms:Decrypt、kms:Encrypt，就不用再懷疑了，問題就在這些周邊服務。這些服務的權限常被忽略，因為大家只盯著最終資源，卻忘了部署管道本身也要通行。

實戰診斷：從一條錯誤訊息往下拆

真正高效的排查，不是記住一堆規則，而是學會讀錯誤。當你遇到錯誤時，可以照下面順序拆解。

第一步：判斷是 synth 還是 deploy

先跑 cdk synth。如果它失敗，先處理合成問題；如果它成功，再看 cdk deploy 是否失敗。這一步可以把問題範圍直接砍半。

第二步：看錯誤關鍵字

如果你看到 AccessDenied、is not authorized、not authorized to assume role，多半是權限問題。如果你看到 Cannot find context、needs to perform AWS calls、Docker、TypeError、Compilation failed，則偏向 synthesis error。關鍵字非常有用，因為 AWS 的錯誤訊息雖然有時候很長，但方向通常不難看出來。

第三步：確認身份與環境

執行 aws sts get-caller-identity，再看 cdk doctor 是否有提示版本或環境異常。很多看似詭異的錯誤，其實是 CDK 與 AWS CLI 版本不一致，或本地設定檔沒有切到正確 profile。確認身份，是最便宜也最有效的動作。

第四步：檢查 bootstrap 與堆疊角色

如果 synth 沒問題但 deploy 持續失敗，請檢查目標帳號和區域是否已完成 bootstrap，並確認 CloudFormation 執行角色具備必要權限。只要是要上傳資產、拉 Docker image、建立 IAM 或使用 KMS，就不能只靠表面上的部署權限。

常見錯誤場景與對應修法

下面這幾種情境，幾乎是 CDK 部署時最常見的雷區。你可以把它們當成對照表，遇到類似訊息時，先朝這些方向查。

情境一：本地能跑，CI 卻失敗

這通常是因為 CI 沒有帶正確的 AWS 憑證，或是 bootstrap 與角色設定和本機不同。先看 CI 的環境變數、OIDC 設定、assume role 是否成功，再看是不是少了 region 或 account。不要假設 CI 會自動繼承你本機的設定，兩者本來就是不同世界。

情境二：第一次部署成功，第二次更新失敗

這很常見，因為第一次只是建立最基本的資源，第二次更新時才碰到新的依賴或新權限。例如你後來加了 KMS、ECR、IAM Role 或跨帳號存取，結果原本的執行角色不夠用了。這時候要比對變更前後差異，找出是哪一個新資源引入了額外權限需求。

情境三：明明有管理員權限還是失敗

有些人會很困惑：我都給了 admin，為什麼還是不能 deploy？原因常常不是 IAM policy 不夠，而是資源層級限制、組織 SCP、Permission Boundary、KMS key policy，或者 CloudFormation 代執行角色的限制。管理員權限不等於無限制，尤其在企業環境裡，外層控制常常比你想像得更嚴。

情境四：刪掉堆疊後再部署就正常

如果刪除後重建突然正常，表示原本堆疊內部可能已經出現資源漂移、手動修改、舊版本角色或被鎖住的依賴。這種情況最好的做法不是每次都刪堆疊，而是先查 drift、比對模板差異，再決定要更新還是重建。否則問題只是被重置，沒有真正解決。

一套能真正落地的排查清單

如果你希望下次再遇到 cdk deploy 報錯時能快點定位，建議固定用這份清單：

1. 先跑 cdk synth，確認是不是合成問題。
2. 執行 aws sts get-caller-identity，確認目前身份。
3. 檢查專案是否有 context lookup、Docker bundling、AMI 或 VPC 查詢。
4. 看 cdk.context.json 是否已過期或引用錯帳號。
5. 確認目標帳號與區域已完成 bootstrap。
6. 檢查 CloudFormation 執行角色是否有建立 IAM、S3、ECR、KMS 等權限。
7. 若錯誤提到 AccessDenied，直接找出被拒絕的 action 與 resource。
8. 若是 CI 環境，確認 token、profile、assume role 與 region 設定完整。

這份清單看起來簡單，但在實戰中很有效。因為大部分問題都不是「CDK 壞了」，而是你和 AWS 之間某個環節沒有接好。把環節拆開來看，問題就會清楚很多。

結語：把錯誤變成流程，而不是靠運氣

CDK 的好處，是讓基礎設施也能像程式碼一樣管理；CDK 的難處，是它把編譯、合成、打包、授權、部署幾個層次揉在一起，錯誤訊息看起來常常很像，但原因卻可能完全不同。面對 cdk deploy 的 Synthesis Error 或權限不足，最重要的不是背更多術語，而是建立穩定的排查順序：先看階段，再看關鍵字，接著驗證身份、上下文、bootstrap 與執行角色。

當你把這套流程養成習慣，很多過去要靠猜的問題，現在幾分鐘就能定位。真正成熟的部署，不是一次都不出錯，而是每次出錯都知道該往哪裡查，並且能把修復動作變成團隊可重複的流程。這才是用好 AWS CDK 的關鍵。