wbroom

如何使用 direnv：安裝、shell hook、.envrc 與專案環境變數自動載入

進目錄自動載入 .envrc，離開即卸載，與 mise 版本 pin 分工。

mise 或 nvm 管好了 Node 版本，进仓库仍要手动 export DATABASE_URL=…、source .env，换 tab 又忘。direnv 在 cd 进目录时加载项目环境变量，离开目录自动卸载；配置写在 .envrc，文档见 direnv.net。

搜尋 direnv 安裝 .envrc shell hook 自动加载环境变量 的人，通常要完成：安裝 direnv、在 zsh/bash 挂 hook、写 .envrc 并 direnv allow、与 mise 等版本管理器分工。步骤以官方文档为准。

安裝 direnvshell hook.envrc · allow · 驗證

direnv 適合谁

01

多项目、多套 env 的开发者

每个仓库有自己的 API 地址、PATH 前缀或 COMPOSE_FILE，不想把 export 写进全局 rc。

02

已用 mise / asdf 的團隊

版本由 mise 管，非密钥类变量由 direnv 管；进目录两件事同时生效。

03

讨厌误用生产配置的人

离开项目目录变量被撤销，降低在错误目录跑迁移或脚本的风险（密钥仍不应提交 Git）。

安裝 direnv（macOS / Linux）

  1. 1

    macOS：Homebrew

    brew install direnv，运行 direnv version 确认 CLI 可用。

  2. 2

    Linux 发行版

    Arch：sudo pacman -S direnv。Debian/Ubuntu 等可查 apt install direnv 是否提供当前版本；若无，按 direnv.net 的 binary 安裝说明操作。

  3. 3

    Nix / 其他

    Nix 用户可用 nixpkgs 中的 direnv；无论渠道，装完都用 direnv version 驗證。

  4. 4

    Windows

    原生 Windows 支持有限；多数人在 WSL 或 Linux/macOS 终端里用 direnv。详见官方平台的安裝页。

激活 shell hook（必做）

direnv 通过 shell hook 在每次提示符刷新前检查当前目录是否有已允许的 .envrc。把下面一行加入 rc 文件（以文档为准）：

# zsh (~/.zshrc)
eval "$(direnv hook zsh)"

# bash (~/.bashrc)
eval "$(direnv hook bash)"

# fish (~/.config/fish/config.fish)
direnv hook fish | source

保存后 source 该文件或重开终端。若 hook 未加载，cd 进含 .envrc 的目录不会出现 direnv 提示。

撰寫 .envrc 并 allow

  1. 1

    在仓库根创建 .envrc

    示例（勿把真实密钥提交 Git）：

# .envrc — 示例，本地值用 .envrc.local 或密钥管理器
export PROJECT_NAME="my-api"
export DATABASE_URL="postgres://localhost:5432/myapi_dev"
PATH_add ./bin

# 若已安裝 mise，可在 .envrc 里加载 mise 环境（见 mise 文档）
# use mise
  1. 2

    首次 allow

    进入目录时 direnv 会提示 direnv: error .envrc is blocked。阅读内容后运行 direnv allow（仅在你信任该文件时）。

  2. 3

    驗證加载

    cd 离开再进入，或 direnv reload。应看到 direnv: export +N 类提示；echo $DATABASE_URL 在目录内有效，cd .. 后变量被撤销。

  3. 4

    團隊与 .envrc.local

    可提交不含密钥的 .envrc，在 .gitignore 里忽略 .envrc.local，并在 .envrc 末尾 source_env_if_exists .envrc.local（语法见官方 Standard library）。

命令作用何时用
direnv allow信任当前目录 .envrcclone 后首次
direnv deny撤销信任怀疑被篡改时
direnv reload重新加载 .envrc改文件后
direnv status查看是否 loaded / blocked排错

direnv 管的是当前 shell 的环境变量，不替代密钥保管（1Password、Vault、CI secrets）。生产连接串不要写进可提交的 .envrc。

和队友对齐本地 env 命名时，可从 wbroom 首页 开浏览器房间快速过一遍；版本 pin 可参考 mise 指南，容器栈见 Docker Compose 入门。

還想核對的問題

direnv 和 mise 的 [env] 重复吗？

可以分工：mise 的 [env] 適合与工具版本绑定的简单变量；direnv 適合复杂 PATH_add、source_env、多文件组合。同一变量只在一处定义，避免互相覆盖。

IDE 终端里不生效？

确认 IDE 启动的 shell 加载了 direnv hook。部分 IDE 需从已 source rc 的终端启动，或使用 direnv 的 editor 集成说明。

每次 pull 都要 allow？

仅当 .envrc 内容哈希变化且 direnv 认为需要重新授权时。这是安全特性；改 .envrc 后按提示 direnv allow。

能用 dotenv 文件吗？

可在 .envrc 里用 dotenv_if_exists .env（stdlib）加载 .env，仍建议 .env 进 .gitignore，仓库只提交加载逻辑。

開始一場會議