Skip to main content

.env文件规范

虽然.env文件非常简单，就是一个text文本，然后就是Key=Value的格式，大多数规范都是说明Key和Value的格式，可以参考 https://dotenvx.com/docs/env-file 但是为更好地集成和使用.env文件，dotenvx提供了一个.env文件数据结构规范，如下：

.env file spec

一个典型的.env文件主要包含三个部分：

  • 元信息：就是.env文件的元信息，如UUID，name, group，sign等，这部分信息通过Front Matter的格式呈现
  • 公钥：用于加密的公钥，dotenvx使用非堆成加密，公钥主要用于数据的加密和签名(sign)验证，在.env文件中使用 DOTENV_PUBLIC_KEY=xxxx来保存公钥。
  • 配置项：就是实际的配置项，dotenvx使用encrypted:前缀来标识加密的配置项，如encrypted:base64_encoded_data ，当然你使用过普通文本值也是可以的，但是你要确保这些文本值不包含敏感信息。

这里还要说明一下元信息：

  • uuid：UUID大家都能理解，这个是唯一标识某一.env文件，方便后续的管理、跟踪和审计。
  • name和group： 这两个字段主要用于标识.env文件的名称和分组，方便对.env文件进行分类和管理，但是名称中不要包含空格，中划线，最好使用下划线，主要是对Environment变量的兼容性考虑。
  • sign：这是一个签名字段，用于验证.env文件的完整性和真实性，dotenvx会在加密时自动生成签名，这样可以确保.env文件没有被篡改。

提示：如果你还需要添加其他原型，如tag，你可以在原型区自行添加，这样就可以方便对.env文件进行管理。

公钥部分，其名称是和profile关联的，这个也就是你经常看到的DOTENV_PUBLIC_KEY_DEV、DOTENV_PUBLIC_KEY_PROD等， 这样可以方便地在不同的环境中使用不同的公钥进行加密和解密。

.env文件变量规范

.env文件使用简单的Key/Value结构保存变量，也就是一个变量(Variable)包括名称(Name)和值(Value)，样例如下：

S3_BUCKET=YOUR_S3_BUCKET
SECRET_KEY=YOUR_SECRET_KEY

变量名命名规范​

变量名需要以字母或者下划线开头，然后是多个字母、数字和下划线的组合，对应的正则表达式为： [a-zA-Z_]+[a-zA-Z0-9_]*

  • DATABASE_URL: ✅ 合法
  • NO-WORK: ❌ 不合法
  • 2MUCH: ❌ 不合法

foobar这样的小写字母也是合法的，但是考量到环境变量的兼容性，建议使用大写字母和下划线的组合。

变量值规范​

变量值可以为简单的字符串，也可以是多行文本，或者包含变量替换的字符串。以下是一些示例：

SIMPLE=xyz123
INTERPOLATED="Multiple\nLines and variable substitution: ${SIMPLE}"
NON_INTERPOLATED='raw text without variable interpolation'
MULTILINE = """
long text here,
e.g. a private SSH key
"""

转义字符(Escape Sequences)，如下：

  • \n: 换行符
  • \r: 回车符
  • \t: Tab
  • \f: Form feed
  • \b: Backspace
  • \" Double-quote
  • \' Single-quote
  • \\ Backslash
  • \uFFFF Unicode escape (4 hex characters to denote the codepoint)

变量替换(Variable Substitution)，也就是在变量值中包含另外变量，如下：

USER=admin
EMAIL=${USER}@example.org
DATABASE_URL="postgres://${USER}@localhost/my_database"
CACHE_DIR=${PWD}/cache
PASSWORD='!@G0${k}k'

提示: 如果变量值中本身就包含${k}这样的值，如password等，请使用单引号，这样就不会进行变量替换。

多行值，采用三重引号(triple-quoted heredoc)，如下：

PRIVATE_KEY="""
-----BEGIN RSA PRIVATE KEY-----
...
HkVN9...
...
-----END DSA PRIVATE KEY-----
"""

命令行替换(Command Substitution)，也就是将命令行执行的结果作为变量值，如下：

API_KEY=$(op read op://MyVault/SomeService/api_key)

备注​

以#开头，如# This is a comment，这个也是和shell脚本一致的。

SDK实现​

由于.env规范并没有什么官方标准，以上是Ruby Dotenv SDK的特性，也被大多数dotenv SDK实现。 但是不同的SDK可能未必全部都实现这些特性，当然也有SDK实现更多的特性，这里只是一个参考。

注意实现: Dotenvx对变量值进行加密，然后转换为base64编码。 但是考量到解密后的后续处理，目前还不支持解密后进行变量或者命令行替换，这个要注意下。