跳轉到

Testcontainers Custom PostgreSQL Image

概念概覽

問題根因

核心知識

問題根因

當 integration test 使用 postgres:16-alpine 而生產環境需要 pg_partman/pg_cron 等擴充套件時，migration 腳本（如 024）會在 testcontainers 中失敗，因為 alpine 映像不包含這些擴充套件。

正確做法

使用 CustomizeRequest(FromDockerfile) 指向包含所需擴充套件的自定義 Dockerfile（如 deployments/docker/postgres.Dockerfile），而非原生 alpine 映像：

req := testcontainers.ContainerRequest{}
testcontainers.CustomizeRequest(testcontainers.GenericContainerRequest{
    ContainerRequest: req,
    FromDockerfile: testcontainers.FromDockerfile{
        Context:    "../../deployments/docker",
        Dockerfile: "postgres.Dockerfile",
    },
})

關鍵陷阱

在 CustomizeRequest 中**不能同時指定 Image 和 FromDockerfile**，會觸發 cannot specify both an Image and Context 錯誤。必須二選一：要麼用現成 image，要麼用自定義 Dockerfile。

最佳實踐

統一使用 deployments/docker/postgres.Dockerfile，確保測試環境與生產環境一致，避免「測試過了但生產炸了」的 migration 問題。

經驗教訓

  • testcontainers alpine 映像缺少擴充套件會讓 migration 靜默失敗，需使用與生產一致的自定義 Dockerfile

  • CustomizeRequest 中 Image 與 FromDockerfile 互斥，同時指定會立即報錯

常見陷阱

  • postgres:16-alpine 不含 pg_partman、pg_cron 等擴充套件，用於 integration test 會讓依賴這些擴充套件的 migration 失敗

  • 同時在 CustomizeRequest 中指定 Image 和 FromDockerfile.Context 會報 cannot specify both 錯誤

最佳實踐

  • integration test 的 PostgreSQL container 統一指向 deployments/docker/postgres.Dockerfile

  • 需要擴充套件時，用 FromDockerfile 而非 Image 欄位

相關概念

來源 Sessions

日期 Session 貢獻摘要

| 2026-03-26 | 59325dc8-0079-4c87-a93e-f2734386d733 | 確立了在 testcontainers 中使用含擴充套件的自定義 PostgreSQL Dockerfile 的正確模式，以及同時指定 Image 與 FromDockerfile 的衝突陷阱 |

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-03-26