# @adonisjs/env 中文文档

规范地址：https://npmcn.com/package/%40adonisjs/env/

版本：7\.1\.0
npm 元数据更新时间：2026-09-04T07:43:26.857Z
中文译文更新时间：2026-11-05T17:13:51.203Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adonisjs/env
原文对照：https://npmcn.com/package/%40adonisjs/env/?lang=original
项目主页：https://github.com/adonisjs/env#readme
源码仓库：https://github.com/adonisjs/env

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：35.9 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：3 个
- 首次发布：2019-09-05T12:06:56.003Z
- 最新版本发布：2026-09-04T07:43:26.493Z
- 近 30 天下载量：787911（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 3 个）

## 中文简介

Node.js 的环境变量管理器

## 安装

```sh
npm install @adonisjs/env
```

也可以使用：`pnpm add @adonisjs/env`、`yarn add @adonisjs/env`、`bun add @adonisjs/env`

## README

# @adonisjs/env (英语)

> AdonisJS 所使用的环境变量解析器和验证器.

[![gh-workflow-image](https://img.shields.io/github/actions/workflow/status/adonisjs/env/checks.yml?style=for-the-badge)](https://github.com/adonisjs/env/actions/workflows/checks.yml "Github action") [![typescript-image](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript)](https://npmcn.com/package/%40adonisjs/env/%22typescript%22) [![npm-image](https://img.shields.io/npm/v/@adonisjs/env.svg?style=for-the-badge&logo=npm)](https://npmjs.org/package/@adonisjs/env "npm") [![license-image](https://img.shields.io/npm/l/@adonisjs/env?color=blueviolet&style=for-the-badge)](https://npmcn.com/package/%40adonisjs/env/LICENSE.md "license")

> **说明:** 这个软件包是框架不可知的,也可以在AdonisJS之外使用.

这个 `@adonisjs/env` 软件包封装围绕加载、解析和验证环境变量的工作流程.

## 设置

从 npm 包注册处安装软件包如下 .

```sh
npm i @adonisjs/env
```

## 信封读取器

这个 `EnvLoader` class 负责从磁盘上装入环境可变文件,并将文件内容作为字符串还原.

```ts
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` 文件并把它们转换成对象.

```ts
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` 文档如下.

```ts
new EnvParser(envContents, { ignoreProcessEnv: true })
```

### 标识符

可以定义用于插入的"识别符". 标识符是一个字符串,它会前置环境变量值,并让您自定义值分辨率.

```ts
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` 还有其他人来管理你的秘密.

## 验证环境变量

一旦有了解析对象,您就可以根据预先定义的策略,选择验证它们. 我们建议验证理由如下.

-   如果缺少一个或多个环境变量, 则提前失败 .
-   对特定数据类型的计算值.
-   拥有类型安全 与运行时间安全.

```ts
import { Env } from '@adonisjs/env'

const validator = Env.rules({
  PORT: Env.schema.number(),
  HOST: Env.schema.string({ format: 'host' })
})
```

这个 `Env.schema` 指的是 [@ poppins/ 验证器- lite](https://github.com/poppinss/validator-lite) `schema` 对象。 确保通过软件包README查看所有可用的方法和选项.

这个 `Env.rules` 方法返回用于验证环境变量的验证符实例。 返回值是具有从计划推断出的类型信息的被验证的对象.

```ts
validator.validate(process.env)
```

## 完整实例

以下是一个完整的例子, 即装入dot-env文件, 并在一次中验证它们 .

> **说明**现有: `process.env` 变量相对于任何文件中定义的变量具有最高优先级.

```ts
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` 文件会更新( 如果存在).

```ts
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`。 。 。 .

```ts
editor.add('SECRET_VARIABLE', 'secret-value', true)
```

这将增加以下一行: `.env.example` 文档.

```env
SECRET_VARIABLE=
```

## 已知例外情况

### (原始内容存档于2019-10-21) (英语). E INVID ENV VARIALS

例外是在环境变量验证例外时提出的。 提出例外的是: `Validation failed for one or more environment variables` 留言.

您可以使用 `error.cause` 属性.

```ts
try {
  validate(envValues)
} catch (error) {
  console.log(error.cause)
}
```

## 常见问题

### @adonisjs/env 是什么？

Node\.js 的环境变量管理器

### 如何安装 @adonisjs/env？

在项目目录运行 npm install @adonisjs/env，或使用 pnpm add / yarn add / bun add。

### @adonisjs/env 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adonisjs/env 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @adonisjs/env 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @adonisjs/env 可以商用吗？

@adonisjs/env 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adonisjs/env 的下载量有多少？

根据 npm 官方下载统计，@adonisjs/env 在 2026/10/05 – 2026/11/03 这 30 天内被下载 787,911 次，日均约 26,264 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adonisjs/env 还在维护吗？

最新版本 7\.1\.0 发布于 2026/09/04（2 个月前）；至今共发布 66 个版本，其中过去 12 个月发布了 3 个；首次发布于 2019/09/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。