Tutoriales de VPS
Docker Compose no aplica .env: prioridades, recreación y configuración
Distingue interpolación, entorno del contenedor y aplicación; localiza sobrescrituras, recrea el servicio correcto y verifica datos sin exponer secretos.

Cambiaste .env, reiniciaste el contenedor y siguen apareciendo la clave API, dirección de base de datos o modo antiguos. Comprueba primero si ese archivo participa en la configuración del servicio y si el contenedor se recreó con los valores nuevos.
.env, la opción --env-file y el campo env_file tienen funciones distintas. Sigue el orden interpolación de Compose → creación del contenedor → configuración de la aplicación. El servicio de ejemplo es app; utiliza el real. Las pruebas emplean variables inocuas, sin imprimir credenciales.
| Síntoma | Primera comprobación | Siguiente paso |
|---|---|---|
| variable is not set | Archivo no cargado o nombre incorrecto | Seleccionar archivo y revisar ${VAR} |
| config ya muestra el valor antiguo | Shell, valor fijo o archivo de sobrescritura | Identificar la fuente dominante |
| config nuevo, contenedor antiguo | Solo restart o proyecto equivocado | Confirmar proyecto y recrear servicio |
| Contenedor nuevo, web sin cambios | Caché o variable de compilación | Actualizar aplicación o compilar según documentación |
| Falla autenticación tras cambiar contraseña de base de datos | Inicialización y cuenta existente no coinciden | Procedimiento de rotación de credenciales |
Según la referencia de restart, restart no actualiza variables de un contenedor existente. Comprueba primero el resultado de configuración.
Supón que tienes .env:
APP_MODE=production
El valor sustituye un campo cuando Compose lo referencia:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
environment:
APP_MODE: "${APP_MODE:?请设置 APP_MODE}"
Es un ejemplo de diagnóstico sin datos de negocio ni puertos publicados. Alpine sirve para observar la configuración, no para sustituir tu imagen de aplicación.
Usa --env-file /实际路径/.env.production si el archivo está en otra ubicación. Crear .env no introduce automáticamente todas sus variables en todos los contenedores. Consulta interpolación y búsqueda de archivos.
Puedes referenciar un archivo dentro del servicio:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
env_file:
- ./app.env
APP_MODE=production dentro de app.env se incorpora al contenedor app. La ruta relativa parte del archivo Compose, no necesariamente del directorio del terminal. Consulta configuración de entorno del servicio.
Otro campo con ${APP_MODE} no obtiene interpolación por tener env_file en el servicio. Interpolación del proyecto e inyección en el contenedor son pasos separados.
Entra en el directorio de despliegue. Aquí se utilizan /opt/myapp, compose.yaml y .env.production:
cd /opt/myapp
pwd
ls -la compose.yaml .env.production
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production config --quiet
Sustituye las rutas. config --quiet valida el análisis sin imprimir todos los valores. Para consultar una variable inocua, ejecuta config sin --quiet en tu terminal privado y localiza el servicio. La salida expandida puede revelar contraseñas y conexiones; no la publiques íntegra.
Si el despliegue usa varios -f, un nombre -p fijo u otro --project-directory, conserva esas opciones. Cambiar -p puede crear otro conjunto de contenedores. 1Panel o Portainer pueden almacenar su propio entorno o Stack; editar un archivo local no actualiza automáticamente ese origen.
Comprueba si el shell define la misma variable. En interpolación, el shell tiene prioridad; --env-file no fuerza todos los valores. En un proyecto de prueba:
APP_MODE=from-shell docker compose --env-file .env config
Aunque .env contenga APP_MODE=production, ${APP_MODE} obtiene from-shell. Si confirmas que producción no debe heredarla, verifica nombre y alcance antes de ejecutar unset APP_MODE en esa sesión y comprobar de nuevo.
En el servicio, environment prevalece sobre env_file:
services:
app:
image: alpine:3.22
command: ["sleep", "3600"]
env_file:
- ./app.env
environment:
APP_MODE: development
Cambiar APP_MODE en app.env no sustituye el valor explícito de environment. Incluso un valor vacío puede prevalecer. Revisa claves además de cadenas antiguas; consulta la prioridad de variables.
Otros archivos Compose también pueden sobrescribir el servicio. config solo sirve para diagnosticar si sus opciones coinciden con el despliegue real.
Comprueba configuración, montajes persistentes y reversión, y utiliza una ventana de mantenimiento. Mantén las opciones de archivos y limita el cambio a app:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production up -d --no-deps app
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production ps app
La referencia de up explica que up recrea los contenedores afectados y conserva los volúmenes montados. Un servicio de una instancia se interrumpe brevemente. Los datos de la capa escribible sin montaje no son persistentes. --no-deps encaja cuando las dependencias funcionan y solo cambia la aplicación; coordina aparte cambios de dependencias.
Si el modelo es correcto y necesitas forzar recreación:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production up -d --no-deps --force-recreate app
No corrige prioridades ni recompila la imagen automáticamente. No necesitas down antes. Evita down -v y borrar volúmenes como supuesto arreglo del entorno.
Para una variable inocua, si la imagen incluye printenv:
docker compose -f /opt/myapp/compose.yaml --env-file /opt/myapp/.env.production exec app printenv APP_MODE
Imágenes mínimas pueden no tenerlo; usa el diagnóstico de la aplicación. No exportes todas las variables para verificar una clave. Prueba después una petición de negocio: running no demuestra que la aplicación adoptara el ajuste.
Revisa comillas e interpolación para los signos de dólar. Los valores entre comillas simples en .env de Compose son literales. La sintaxis Bash no es universal para archivos env y docker run --env-file se comporta de otra forma. Prueba primero con DEMO_VALUE inocuo.
Algunas versiones muestran $$ escapado al serializar config. Eso no demuestra que el contenedor reciba dos dólares.
Para que la variable se expanda en el shell del contenedor, utiliza $$:
services:
app:
image: alpine:3.22
environment:
APP_MODE: production
command: ["sh", "-c", "printf '%s\\n' \"$$APP_MODE\"; sleep 3600"]
La especificación de interpolación explica $$. El ejemplo llama explícitamente a sh -c; un comando en forma de array no activa por sí solo la expansión del shell y la imagen debe incluirlo.
Revisa la aplicación. Laravel puede guardar caché de configuración; las variables frontend pueden quedar incorporadas durante compilación; otros servicios guardan ajustes en la base de datos tras inicializar. Sigue sus procedimientos de caché, compilación y almacenamiento.
Una contraseña de inicialización no rota una cuenta ya existente. Con un volumen previo, cambia la cuenta mediante el procedimiento admitido por la base de datos y sincroniza las credenciales de la aplicación. Guarda respaldo y reversión; borrar el volumen para repetir la inicialización destruye datos.
La reparación exige config correcto con las mismas opciones, contenedor adecuado con valores nuevos, petición de negocio exitosa y datos/dependencias saludables.
El artículo original verificó cuatro YAML con Docker Compose 2.17.3, prioridad del shell, rechazo de un valor obligatorio vacío y representación del dólar literal. El valor predeterminado era production, el del shell from-shell y el explícito development. No había daemon Docker operativo: no se recrearon contenedores ni se verificó una carga de producción en VPS.
Para continuar: