如何安裝 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，并在进出目錄时看到變數生效与消失。

direnv 解决什么问题

上游：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 对照

適合

多儲存庫切换、Node/Python/Go 各要不同 PATH、staging/prod 端点按目錄区分。

不適合

只想全局一次 export；或 CI 容器（在 Dockerfile/ workflow 里设 env 更直接）。