仓库留键名，本机留明文值
仓库放一份 .env.example，只写键名与占位值；明文值放在各人本机的 .env。密钥既不进代码，也不进镜像层与前端构建产物。
建仓库与协作约定
仓库要做三件事：给多人一个共同基线、为每次改动留下可追溯的记录、给密钥与本地配置一道明确的边界。这三件事都在第一次提交之前决定。
1这一页管什么
仓库的初始状态、协作约定与密钥边界；本轮做什么不在这里决定。
- 管三件事。第一次提交放什么、主干分支与变更的命名归档约定、密钥与本地配置的边界。
- 不交由这一页。本轮实现哪些能力、每条做到什么算完成，属定边界与规约；分层、命名、安全红线属工程规范各页；目录结构与启动方式属骨架一页。
- 落法。协作约定写进 README 与安全规范；密钥检索做成规则或提交前钩子自动执行，不依赖人工记忆。
对应的课程知识点：软件配置管理（Software Configuration Management, SCM）中的版本控制、分支策略与基线（baseline）；可追溯性（traceability）——每一次改动都能追溯到一条规约；机密管理（secrets management）中的配置项与密钥分离。这三件事都在第一次提交之前决定，因为后补的代价高于先写的代价。
2第一次提交放什么
只有三样，且顺序不能颠倒。
| 文件 | 写什么，为什么必须先在 | 怎么检查 |
|---|---|---|
README.md | 项目的一句话定位，以及本机从克隆到启动的完整步骤。它是别人拿到仓库后唯一的入口；步骤写不全，协作就退化为口头交接 | 组内另一名成员在自己机器上照 README 从零启动，在哪一步受阻就补哪一步 |
.gitignore | 依赖目录、构建产物、本机配置与密钥文件、编辑器与系统临时文件。过滤规则仅对加入之后的提交生效；先写代码再补，提交历史中已留下痕迹 | 在提交历史中检索依赖目录、构建产物与本机配置文件的路径，检索不到即通过 |
LICENSE | 开源许可（可选），涉及后续是否公开演示与复用 | 组长在 README 中写明本项目的许可选择；留空也要写明「未选择」及原因 |
顺序不能颠倒的理由只有一条：后补的代价高于先写的代价——过滤规则漏掉的提交已经进了历史，README 缺的步骤已经被口头交接替代。
3协作约定
约定要写在 README 里，而不是靠默契；每条都要能检查。
| 条目 | 具体规定，为什么这样定 | 怎么检查 |
|---|---|---|
| 主干分支（main）唯一 | 如 main；保护规则在写入第一行代码之前设好，主干上不留半成品。基线只有一条，「当前版本」这个说法才有确定含义 | 直接向主干分支推送应被拒绝；主干分支上任一提交都应能启动 |
| 每次改动开一条变更（change） | 以 YYYY-MM-DD-短横小写英文名 命名，验收通过后归档；归档后的需求规约并入主干，成为下一次改动的既有约定。命名统一，变更之间才可排序、可检索 | 变更目录命名逐个核对；归档后的需求规约能在主干分支检索到 |
| 提交信息写清依据 | 写「改了什么、依据哪条规约」，不写 update、fix 这类无信息量的词。课程后期复盘要顺着提交历史说明每个人的贡献，信息缺失则无法追溯 | 随机抽三条提交信息，能说出各自对应哪条规约即通过 |
| 每人各自克隆并跑通一次 | 确认不存在「仅在某台机器上可运行」的情形。环境相关的隐式依赖只有在别人的机器上才会暴露 | 尚未参与过启动的成员在自己机器上从零启动成功，且无需任何人工补充说明 |
分工不是「各写各的模块」：规约、规范与骨架这三件事要全组一起定，因为它们决定所有人后续怎么写。这三件事的评审对象是文件，不是印象。
4密钥的边界
一句话：明文值只存在于本机环境，其余任何位置只出现键名。
边界要列到具体位置
不进代码、不进镜像层、不进前端构建产物、不进日志与错误信息、不进问题单与截图。只写「不外泄」没有检查点；列到位置才能逐处检索。
验证手段是检索，不是承诺
在仓库中检索本项目的密钥字符串，含全部提交历史；能检索到即说明该边界已被破坏。这项检查应当做成一条规则，每次提交前后自动执行，而不依赖人工记忆。
对应的课程知识点：最小权限原则、机密管理中的配置项与密钥分离、纵深防御（defense in depth）——单一位置失效不至于导致密钥外泄。密钥一旦进入提交历史，删除文件不足以消除风险，历史中仍可检出，处理办法是立即轮换（rotate）该密钥并重写提交历史。