wbroom

How to use direnv: install, shell hook, .envrc, and per-project environment

Load .envrc on cd, unload on leave — env vars beside mise toolchain pins.

mise or nvm pins Node, but you still hand-export DATABASE_URL or source .env in every repo tab. direnv loads project environment variables when you cd in and unloads when you leave. Config lives in .envrc; docs at direnv.net.

Searchers looking for install direnv envrc shell hook load environment variables need: install direnv, hook zsh/bash, author .envrc, run direnv allow, and split duties with mise. Steps follow the official docs.

安装 direnvshell hook.envrc · allow · 验证

Who direnv fits

01

多项目、多套 env 的开发者

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

02

已用 mise / asdf 的团队

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

03

讨厌误用生产配置的人

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

Install 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。详见官方平台的安装页。

Activate the 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 提示。

Author .envrc and 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 入门。

Questions worth checking

Does direnv duplicate mise [env]?

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

Not working in the IDE terminal?

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

Re-allow on every pull?

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

Can I use a dotenv file?

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

Start a meeting