@adonisjs/env (英语)
AdonisJS 所使用的环境变量解析器和验证器.
说明: 这个软件包是框架不可知的,也可以在AdonisJS之外使用.
这个 @adonisjs/env 软件包封装围绕加载、解析和验证环境变量的工作流程.
设置
从 npm 包注册处安装软件包如下 .
npm i @adonisjs/env
信封读取器
这个 EnvLoader class 负责从磁盘上装入环境可变文件,并将文件内容作为字符串还原.
import { EnvLoader } from '@adonisjs/env'
const lookupPath = new URL('./', import.meta.url)
const loader = new EnvLoader(lookupPath)
const envPaths = loader.getPaths()
const envFiles = await loader.load()
getPaths 返回装入器可能加载的每个 dot-env 文件的绝对路径,按优先级顺序。 它包括不存在且不从文件系统读取的文件.
这个 load 返回值是具有以下属性的一系列对象.
path: 已装入的点- env文件的路径 .contents:文件的内容.
以下为已装入的文件列表 。 数组由文件的优先级排序 。 第一个文件具有最高优先权,必须覆盖最后一个文件中的变量.
| 优先权 | 文件名称 | 环境 | 我应该 .gitignore 这个 | 页:1 |
|---|---|---|---|---|
| 第1个 | .env.[NODE_ENV].local | 当前环境 | 对 | 装入时 NODE_ENV 设定 |
| 第二届 | .env.local | 全体 | 对 | 已装入除此之外的所有环境中 test 或者说 testing 环境 |
| 第三届 | .env.[NODE_ENV] | 当前环境 | 没有 | 装入时 NODE_ENV 设定 |
| 第四届 | .env | 全体 | 取决于 | 装入所有环境。 你应该 .gitignore 存储此文件中的秘密时 |
| 第五届 | .env.example | 全体 | 没有 | 装入时 loadExampleFile 已启用 |
信封页
这个 EnvParser 分类负责解析 .env 文件并把它们转换成对象.
import { EnvParser } from '@adonisjs/env'
const envParser = new EnvParser(`
PORT=3000
HOST=localhost
`)
console.log(await envParser.parse()) // { PORT: '3000', HOST: 'localhost' }
返回值为 parser.parse 是带有密钥值对的对象。 剖析器也支持插入.
默认情况下, 解析器倾向于已有 process.env 价值当它们存在时。 然而,您可以指示解析器忽略已有的 process.env 文档如下.
new EnvParser(envContents, { ignoreProcessEnv: true })
标识符
可以定义用于插入的"识别符". 标识符是一个字符串,它会前置环境变量值,并让您自定义值分辨率.
import { readFile } from 'node:fs/promises'
import { EnvParser } from '@adonisjs/env'
EnvParser.identifier('file', (value) => {
return readFile(value, 'utf-8')
})
const envParser = new EnvParser(`
DB_PASSWORD=file:/run/secret/db_password
`)
console.log(await envParser.parse()) // { DB_PASSWORD: 'Value from file /run/secret/db_password' }
当你使用保密管理器时,这个可能有用 Docker Secret, (中文(简体) ), HashiCorp Vault, (中文(简体) ), Google Secrets Manager 还有其他人来管理你的秘密.
验证环境变量
一旦有了解析对象,您就可以根据预先定义的策略,选择验证它们. 我们建议验证理由如下.
- 如果缺少一个或多个环境变量, 则提前失败 .
- 对特定数据类型的计算值.
- 拥有类型安全 与运行时间安全.
import { Env } from '@adonisjs/env'
const validator = Env.rules({
PORT: Env.schema.number(),
HOST: Env.schema.string({ format: 'host' })
})
这个 Env.schema 指的是 @ poppins/ 验证器- lite schema 对象。 确保通过软件包README查看所有可用的方法和选项.
这个 Env.rules 方法返回用于验证环境变量的验证符实例。 返回值是具有从计划推断出的类型信息的被验证的对象.
validator.validate(process.env)
完整实例
以下是一个完整的例子, 即装入dot-env文件, 并在一次中验证它们 .
说明现有:
process.env变量相对于任何文件中定义的变量具有最高优先级.
import { Env } from '@adonisjs/env'
const env = await Env.create(new URL('./', import.meta.url), {
PORT: Env.schema.number(),
HOST: Env.schema.string({ format: 'host' })
})
env.get('PORT') // is a number
env.get('HOST') // is a string
env.get('NODE_ENV') // is unknown, hence a string or undefined
信封编辑器
Env 编辑器可用于编辑 dot-env 文件并坚持磁盘上的更改. 只有 .env 财务报告和审定财务报表 .env.example 文件会更新( 如果存在).
import { EnvEditor } from '@adonisjs/env/editor'
const editor = await EnvEditor.create(new URL('./', import.meta.url))
editor.add('PORT', 3000)
editor.add('HOST', 'localhost')
// Write changes on disk
await editor.save()
也可以插入空值 .env.example 将最后一个参数设置为 true。 。 。 .
editor.add('SECRET_VARIABLE', 'secret-value', true)
这将增加以下一行: .env.example 文档.
SECRET_VARIABLE=
已知例外情况
(原始内容存档于2019-10-21) (英语). E INVID ENV VARIALS
例外是在环境变量验证例外时提出的。 提出例外的是: Validation failed for one or more environment variables 留言.
您可以使用 error.cause 属性.
try {
validate(envValues)
} catch (error) {
console.log(error.cause)
}