dotenv核心概念

dotenvx是基于.env文件进行配置项加解密的，所以dotenvx的核心概念就是.env文件。

profile

profile在很多框架中都有介绍，如Node.js的NODE_ENV，Spring Boot的active profile等，主要是为了区分不同的环境配置，如开发环境、测试环境、生产环境等，如我们熟悉的dev、test、prod等。当然在实际的部署中，还会有更复杂的情况，如不同的数据中心，对应的名称可能为us_east_1_prod等。

考虑到对环境变量的友好，不建议profile名称中包含空格、中划线(-)、点(.)等字符，最好统一使用下划线(_)来分隔，如region1_prod, us_east_1_prod等。

在dotenvx中，.env文件和profile的关联是通过文件命名规范来实现的，profile作为文件名的后缀，如.env.dev、.env.prod等。

在dotenvx命令行中，profile是作为命令行全局参数传入的，如dotenvx --profile test decrypt，这样就可以根据profile来选择对应的.env文件进行相关的操作。

env-file

env-file就是具体的.env文件，是承载配置项的文件，同时包括元信息、加密公钥和配置项等。

dotenvx的.env文件选择是通过子命令进行的，如dotenvx decrypt -f .env.dev，然后对具体的.env文件进行相关的操作。

提示: 你可以通过--profile参数通过profile查找.env文件，也可以通过-f .env.test参数直接指定.env文件，如果你未指定任何参数，则dotenvx会自动查找当前目录下的.env文件。这两者具体要使用哪种方式，取决于你的使用习惯，如我更多的是通过-p profile，通过profile更方便理解，此外dotenvx还会查找.properties文件等，profile方式更透明一些。

.env.keys

.env.keys文件是dotenvx的私钥文件，主要用于解密.env文件中的配置项。目前有几种方式可以存放.env.keys文件，如下图：

$HOME
   - .env.keys
   - .dotenvx
        - .env.keys.json
        - .env.g_default
        - .env.g_github
   - project-1
        - .env
        - .env.keys

项目级别：也就是在项目目录下存放.env.keys文件
用户级别：在用户目录下存放.env.keys文件，如$HOME/.env.keys，可以作为全局的私钥文件
库级别：在用户目录下的.dotenvx/.env.keys.json文件中存放私钥文件，会保存dotenvx涉及到的所有私钥，包括从其他人员或者系统导入的私钥。

dotenvx会在.env文件中存放公钥，所以在查找要解密的私钥时，首先会读取.env文件中的公钥，然后根据公钥在.env.keys.json 文件中查找对应的私钥，如果没有找到，则会在当前目录或者父目录(递归)下查找.env.keys文件，最后是环境变量 DOTENV_PRIVATE_KEY。

在实际的开发中，原则上建议不要在项目目录下存放.env.keys文件，考虑到目前大多数程序员都在使用AI，如果将.env.keys防止在项目目录下，可能会被AI Agent或者AI IDE扫描，造成秘钥泄露，所以建议将.env.keys文件中的private key都存放在用户目录下的 .dotenvx/.env.keys.json中，不会造成秘钥泄露，同时可以统一管理众多私钥。如果涉及的秘钥不多，$HOME/.env.keys文件也是可以的。

.env.keys文件的格式如下，主要就是front matter保存元信息，另外就是不同profile的秘钥信息

# ---
# uuid: 019848e9-caa9-7683-87db-a53b6342c808
# ---

DOTENV_PRIVATE_KEY=c4e79fecc6bfeb1fe3bf4d
DOTENV_PRIVATE_KEY_TEST=82056174ece6e87e76
DOTENV_PRIVATE_KEY_PERF=fc9067f0a82c022fedbc

全局秘钥存储的文件路径为$HOME/.dotenvx/.env.keys.json，其格式如下：

{
  "version": "0.1.0",
  "metadata": {
    "uuid": "09f406f9-82bc-4c0a-910b-259c60cd84f6"
  },
  "keys": {
    "023cf16fd02bdb0d938d31e6b5876": {
      "public_key": "023cf16fd02bdb0d938d31e6b5876",
      "private_key": "0967931055d80d414c366bc3",
      "path": "/Users/user1/PycharmProjects/py-demo/.env",
      "group": null,
      "name": null,
      "profile": null,
      "comment": null,
      "timestamp": "2025-08-16T20:57:50.304166+08:00"
    }
  }
}

.env.keys.json文件的格式主要包括三部分：

版本号：主要标识当前文件格式的版本，如果后续文件格式有升级，可以通过版本号进行区分。
元数据：主要包括文件的UUID等信息，这个主要方便后续的文件交换和备份等，当前uuid是必须的字段，用于唯一标识一个 .env.keys.json文件。
keys：主要是公钥和私钥的映射关系，同时不包括一些密钥对的元信息，如group，path等

format输出

dotenvx支持多种个数输出，主要包括：

text: 这个也是.env文件的默认格式，主要是Key=Value的格式，适合copy和编辑
shell: 输出export KEY=VALUE格式，适合在shell中使用，直接导出为环境变量，如 eval $( dotenvx decrypt --stdout --format shell )就可以将解密后的配置项导出为环境变量
json: 输出为JSON格式，适合程序处理，如在其他语言中集成dotenvx，通过执行dotenvx decrypt --stdout --format json 就可以获取解密后的配置项的stdout输出，然后解析json即可
csv: 输出为CSV格式，适合数据处理和分析，如和DuckDB配合等，这种方式非常方便的

默认会输出为text格式，如果你需要其他格式，可以通过--format参数进行指定。

目前format主要用在dotenvx decrypt --stdout --format <format>和dotenvx get <key> --format <format>这两个命令中。

profile​

env-file​

.env.keys​

format输出​

profile

env-file

.env.keys

format输出