direnv 使用指南：按目录自动加载环境变量

很多项目都需要环境变量：数据库地址、API 地址、运行模式、密钥路径。手动 source .env 很容易忘。direnv 的作用就是进入目录时自动加载，离开目录时自动卸载。

安装

Debian / Ubuntu：

1
sudo apt install direnv

Shell 里启用 hook：

1
eval "$(direnv hook bash)"

zsh 用户放到 .zshrc：

1
eval "$(direnv hook zsh)"

基本用法

在项目根目录创建 .envrc：

1
export APP_ENV=local
2
export DATABASE_URL=sqlite:///dev.db
3
layout python .venv

第一次需要允许：

1
direnv allow

之后进入目录会自动加载变量，离开目录会清掉。

和项目工具配合

Node 项目可以配合 .nvmrc 和 nvm 安装和使用教程，Python 项目可以配合 pyenv 安装与使用指南 或 uv 安装和使用教程。

一个常见 .envrc：

1
export APP_ENV=local
2
export SECRET_KEY=dev-only
3
export DATABASE_URL=postgresql://localhost/app
4
PATH_add .venv/bin

常见问题

.envrc 里不要放生产密钥。它很容易被提交。可以提交 .envrc.example，真实 .envrc 加进 .gitignore。

改完 .envrc 后必须重新执行：

1
direnv allow

这是安全设计，避免你进入陌生仓库时自动执行危险脚本。

总结

direnv 适合多项目开发机。它解决的不是部署配置，而是本地切项目时的环境隔离。用好 .envrc、.gitignore 和示例文件，能少很多“我本地为什么读不到变量”的问题。更多细节看 direnv 官方文档。