Caveman 简洁回答

127.0.0.1 inside API container means the API container itself, not Postgres. Postgres runs in its own container. From inside Docker Compose, reach it by its service name. Your laptop works because the port is published to the host's localhost.

Fix: point the host at the Compose service name.

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      retries: 15
  api:
    build: .
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/postgres
    depends_on:
      db:
        condition: service_healthy

Use db (your service name) as the host, in DATABASE_URL or PGHOST. Don't hardcode localhost in code.

The healthcheck plus condition: service_healthy is a second fix. Plain depends_on only waits for the container to start, not for Postgres to accept connections. Without the healthcheck you can still get ECONNREFUSED on cold start, even with the right host.

Other causes to check:

• API runs on the host, not in Compose: localhost:5432 is correct there. Make sure ports: ["5432:5432"] is set on db.
• API in a different Compose project or network: put both on a shared network, or use host.docker.internal:5432.
• Postgres listening only on a unix socket: the official image already listens on *. Only custom configs need listen_addresses = '*'.

Check the connection from inside the API container: docker compose exec api sh -c 'nc -zv db 5432'.