.env 文件必须进 .gitignore，因其存储数据库密码、APP_KEY、API密钥等敏感信息，提交至远程仓库将导致严重安全风险；需手动添加规则并处理已跟踪情况，配合 .env.example 协作使用，部署时须单独注入配置而非从Git获取。

为什么 .env 文件必须进 .gitignore

因为 .env 里通常存着数据库密码、APP_KEY、API 密钥等敏感信息，一旦被提交到远程仓库，就等于把钥匙交到所有人手上。Git 默认不会自动忽略它，不手动加规则，第一次 git add . 就可能直接推上去。

如何正确写入 .gitignore 并确保生效

在项目根目录的 .gitignore 文件末尾追加一行：

.env

但这只是基础操作，真正容易出问题的是以下三点：

• 如果 .env 已被 Git 跟踪过（即之前 commit 过），再加这行也没用 —— 先运行 git ls-files | grep ".env" 确认是否已追踪；有输出说明已被记录
• 已追踪状态下，需先执行 git rm --cached .env（注意带 --cached，保留本地文件）
• 再 git commit -m "remove .env from tracking"，之后新增的 .env 才会被真正忽略

要不要加 .env.example？加在哪？

要加，而且必须加。它不是可选配件，是协作刚需：

GitHub Actions Secret Exposure Audit

审计 GitHub Actions 工作流文件的密钥泄露风险，例如 pull_request_target 密钥使用、密钥回显命令及未固定版本的 Action 密钥传递。

下载

立即学习“PHP免费学习笔记（深入）”；

• .env.example 放在项目根目录，内容和 .env 格式一致，但所有值设为占位符（如 DB_HOST=localhost、APP_KEY=your_app_key_here）
• 这个文件要提交进 Git，让新成员克隆后能快速复制一份 cp .env.example .env 并填值
• 别忘了在 .gitignore 里明确排除真实文件：

  .env<br>!.env.example

  ，否则 !.env.example 可能被前面的 .env 规则覆盖失效

部署时 .env 文件丢了怎么办

线上环境没 .env 是最常见“500 错误”源头之一，尤其当 CI/CD 脚本只拉代码、不传配置时：

• 确认部署脚本是否跳过了 .env —— 它不该从 Git 拉，而应由运维单独注入（如 Ansible 模板、K8s Secret 挂载、或部署前 scp 上传）
• 检查 Web 服务器工作目录是否真是项目根目录：ThinkPHP 要求 .env 在入口文件（public/index.php）的上两级，不是放在 public/ 下
• 运行 php think env:check（TP6+ 自带命令）验证环境变量是否加载成功，比盲猜快得多

真正麻烦的从来不是怎么写 .gitignore，而是有人改完 .env 忘了清 runtime/config.php 缓存，或者把 .env 放进了 public/ 目录导致 Nginx 直接暴露下载。