hereink

如何安装 direnv：.envrc 基础、项目目录 allow 与自动加载环境变量

安装 direnv，写 .envrc 并 allow，进出目录自动加载环境变量。

每个仓库都有自己的 API key、数据库 URL 和 PATH 补丁，却不想把 .env 手动 source 一遍。direnv 在项目目录里读 .envrc，你 cd 进去就加载环境变量，离开就卸载。本教程覆盖 macOS/Linux 安装、shell hook、.envrc 基础语法、在项目目录执行 direnv allow、以及自动加载与卸载，面向 hereink 读者常用的多仓库终端工作流。

检索词是如何安装 direnv 并写 .envrc 让项目环境变量自动加载。读完应能安装 direnv、写第一条 .envrc、在仓库根目录 direnv allow，并在进出目录时看到变量生效与消失。

安装brew · apt · nix
配置.envrc · allow
行为cd 进 · cd 出

direnv 解决什么问题

按目录隔离环境

全局 export 会污染所有 shell；只在当前项目需要的变量应随目录挂载。direnv 在 cd 时注入，cd .. 时撤销，减少「忘改 PATH 跑错脚本」。

与 .env 文件配合

.envrc 可以 dotenv 加载已有 .env，或直接用 export。密钥仍应进 .gitignore，只提交不含秘密的 .envrc 模板。

上游：github.com/direnv/direnv，文档 direnv.net。安装后运行 direnv version 确认。

安装 direnv

  1. 1
    macOS（Homebrew）

    brew install direnv。验证：which direnv 与 direnv version。

  2. 2
    Linux（发行版包）

    Debian/Ubuntu：sudo apt update && sudo apt install direnv。Fedora：sudo dnf install direnv。Arch：sudo pacman -S direnv。

  3. 3
    挂到 shell（必做）

    在 ~/.zshrc 或 ~/.bashrc 末尾加：eval "$(direnv hook zsh)"（bash 用 bash）。新开终端或 source ~/.zshrc。

  4. 4
    fish

    在 ~/.config/fish/config.fish：direnv hook fish | source。见官方文档其他 shell。

.envrc 基础

.envrc 是 shell 脚本片段，放在项目根（或子目录）。常用写法：

# 直接 export
export API_BASE=https://api.staging.example.com
export NODE_ENV=development

# 把本地 bin  prepend 到 PATH
PATH_add ./bin

# 加载同目录 .env（dotenv 需 direnv 标准库，见文档）
dotenv_if_exists

不要把真实 token 提交到 git。团队可提交 .envrc 里的非敏感默认值，每人本地 .env 放密钥，由 dotenv_if_exists 读取。

在项目目录 allow

首次进入含 .envrc 的目录，direnv 会拒绝执行，直到你显式信任该文件：

cd ~/projects/my-app
# direnv: error .envrc is blocked. Run `direnv allow` to approve its content.

direnv allow
# direnv: loading ~/projects/my-app/.envrc
echo $API_BASE

direnv allow 会在项目里写入哈希白名单（.direnv/），.envrc 内容变更后需再次 direnv allow。这是 deliberate 安全设计：任意 clone 的仓库不能静默改你的环境。

自动加载与离开卸载

hook 生效后，无需每次手动 source：

cd ~/projects/my-app    # 加载 .envrc
env | grep API_BASE

cd ~                    # 卸载该项目变量
env | grep API_BASE     # 应无输出

嵌套目录：子目录若有独立 .envrc，进入子目录会叠加或替换规则（见 direnv.net 的 source_up）。 monorepo 常在根目录统一 PATH_add 工具链。

与手动 source .env 对照

方式何时加载离开目录
source .env手动每次变量仍留在 shell
direnv + .envrccd 自动自动卸载
IDE 注入打开项目取决于 IDE
适合
多仓库切换、Node/Python/Go 各要不同 PATH、staging/prod 端点按目录区分。
不适合
只想全局一次 export；或 CI 容器（在 Dockerfile/ workflow 里设 env 更直接）。
.envrc 改了为什么又不生效？

内容变更后运行 direnv allow 或 direnv reload。direnv 对比允许时的哈希，防止静默篡改。

和 asdf/mise 冲突吗？

可以并存：版本管理器在 shell 层，direnv 在目录层补 PATH 与项目变量。常见做法是在 .envrc 里 use mise 或调用工具提供的 direnv 集成（见各自文档）。

Windows 能用吗？

官方主要支持 Unix shell。WSL 内按 Linux 步骤安装 hook 即可。原生 PowerShell 支持有限，见 direnv 文档当前状态。

环境对齐后画一张图

终端里把 staging 端点与依赖服务理清后，架构仍适合摊在同一张白板上。见 如何创建空间。

即刻开会