hyperf 单机部署最稳妥方式是挂载 .env 文件至容器 /app/.env；需置于项目根目录，格式为 key=value，禁止空格与变量展开；docker compose 中应通过 volumes 挂载而非 env 指令，且不可提交至 git。
Hyperf 单机部署时，用 .env 文件注入环境变量是最稳妥、最常用的方式——它不改动镜像、不暴露敏感信息、还能快速切换开发/测试/生产配置。
Hyperf 项目中 .env 文件的正确位置与格式
Hyperf 默认使用 vlucas/phpdotenv 加载根目录下的 .env 文件。该文件需放在项目根目录（即 docker-compose.yml 和 Dockerfile 同级），内容为纯键值对：
- 每行一个变量，格式为
KEY=VALUE（等号前后不加空格） - 支持
#开头的注释和空行 - 不支持变量展开（如
DB_URL=mysql://${DB_HOST}:${DB_PORT}/test不生效） - 示例：
APP_ENV=prod<br>APP_DEBUG=false<br>DB_HOST=db<br>DB_PORT=3306<br>DB_DATABASE=hyperf<br>DB_USERNAME=root<br>DB_PASSWORD=123456<br>REDIS_HOST=redis<br>REDIS_PORT=6379
Docker Compose 中加载 .env 的两种方式
注意区分：Docker Compose 自动加载的是 宿主机上的 .env 文件（用于替换 compose 文件里的变量），而 Hyperf 应用读取的是 挂载进容器内的 /app/.env。两者用途不同，不能混用。
-
方式一：挂载 .env 到容器内（推荐）
在docker-compose.yml中通过volumes显式挂载，确保 Hyperf 启动时能读到：
services:<br> hyperf:<br> build: .<br> volumes:<br> - ./:/app<br> - ./envs/.env.prod:/app/.env:ro # 挂载生产环境配置，只读
-
方式二：用 --env-file 启动时注入（适合调试）
直接传给容器运行时环境，Hyperf 可通过getenv()或$_ENV读取，但需确认框架是否启用该机制（Hyperf 默认优先读.env文件，此方式作为补充）：
docker run --env-file ./envs/.env.prod -v $(pwd):/app -p 9501:9501 hyperf-image
避免踩坑的三个关键点
-
不要把 .env 提交到 Git：加入
.gitignore，只保留.env.example作为模板供团队初始化 -
不要在 Dockerfile 中写 ENV 敏感值：比如
ENV DB_PASSWORD=xxx会固化到镜像层，有泄露风险；所有运行时变量都应外置 -
Hyperf 配置优先级要清楚：框架加载顺序通常是
.env文件 → 环境变量（getenv）→ 配置文件硬编码，默认以.env为准；若需覆盖，可在config/autoload/constants.php中调用putenv()，但不推荐
单机部署完整流程示例
假设项目结构如下：
hyperf-project/<br>├── docker-compose.yml<br>├── Dockerfile<br>├── .env.example<br>├── envs/<br>│ ├── .env.dev<br>│ └── .env.prod<br>└── app/
- 构建镜像：
docker build -t hyperf-app . - 启动生产实例：
docker-compose --env-file envs/.env.prod up -d（此处--env-file是给 compose 解析自身变量用，非给 Hyperf） - 实际生效靠挂载：
volumes: ["./envs/.env.prod:/app/.env:ro"] - 验证是否加载成功：进入容器执行
php bin/hyperf.php di:info | grep APP_ENV，或查看日志中是否打印APP_ENV=prod
