# @cubejs-backend/dotenv 中文文档

规范地址：https://npmcn.com/package/%40cubejs-backend/dotenv/

版本：9\.0\.2
npm 元数据更新时间：2025-03-07T21:17:12.957Z
中文译文更新时间：2026-11-11T04:11:04.989Z
软件包许可：BSD-2-Clause

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

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

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

- 包体积（解压后）：27.3 kB，15 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=8
- 运行依赖：0 个
- 首次发布：2021-02-11T22:21:02.817Z
- 最新版本发布：2021-02-11T22:21:03.501Z
- 近 30 天下载量：302241（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

从.env 文件装入环境变量

## 安装

```sh
npm install @cubejs-backend/dotenv
```

也可以使用：`pnpm add @cubejs-backend/dotenv`、`yarn add @cubejs-backend/dotenv`、`bun add @cubejs-backend/dotenv`

## README

# 多腾v

![dotenv](https://raw.githubusercontent.com/motdotla/dotenv/master/dotenv.png)

Dotenv 是一个零依赖模块,它从一个 `.env` 文件输入 [`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env)。在环境中与代码分开的存储配置基于 [十二因素应用程序](http://12factor.net/config) 方法.

[![BuildStatus](https://img.shields.io/travis/motdotla/dotenv/master.svg?style=flat-square)](https://travis-ci.org/motdotla/dotenv) [![Build status](https://ci.appveyor.com/api/projects/status/github/motdotla/dotenv?svg=true)](https://ci.appveyor.com/project/motdotla/dotenv/branch/master) [![NPM version](https://img.shields.io/npm/v/dotenv.svg?style=flat-square)](https://www.npmjs.com/package/dotenv) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard) [![Coverage Status](https://img.shields.io/coveralls/motdotla/dotenv/master.svg?style=flat-square)](https://coveralls.io/github/motdotla/dotenv?branch=coverall-intergration) [![LICENSE](https://img.shields.io/github/license/motdotla/dotenv.svg)](https://npmcn.com/package/%40cubejs-backend/dotenv/LICENSE) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org/)

## 安装

```bash
# with npm
npm install dotenv

# or with Yarn
yarn add dotenv
```

## 使用量

在应用程序中,请尽快要求和配置 dotenv .

```javascript
require('dotenv').config()
```

创建一个 `.env` 在您的工程根目录中的文件。 添加 新线上的环境变量,形式如下: `NAME=VALUE`。 。 。 . 例如:

```dosini
DB_HOST=localhost
DB_USER=root
DB_PASS=s1mpl3
```

`process.env` 现在有您定义的键和值 `.env` 文档.

```javascript
const db = require('db')
db.connect({
  host: process.env.DB_HOST,
  username: process.env.DB_USER,
  password: process.env.DB_PASS
})
```

### 预装

你可以用这个 `--require` (单位:千美元)`-r`(中文(简体) ) [命令行选项](https://nodejs.org/api/cli.html#cli_r_require_module) 以预装多腾v。 通过这样做,你不需要在应用程序代码中要求并加载多腾v. 这是在使用 `import` 改为 `require`。 。 。 .

```bash
$ node -r dotenv/config your_script.js
```

以下配置选项在格式中作为命令行参数支持 `dotenv_config_<option>=value`

```bash
$ node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env
```

此外,还可以使用环境变量设置配置选项. 命令行参数会在这些参数之前 .

```bash
$ DOTENV_CONFIG_<OPTION>=value node -r dotenv/config your_script.js
```

```bash
$ DOTENV_CONFIG_ENCODING=latin1 node -r dotenv/config your_script.js dotenv_config_path=/custom/path/to/.env
```

## 配置

`config` 会读你的 `.env` 文件、 解析内容、 指派到 [`process.env`](https://nodejs.org/docs/latest/api/process.html#process_process_env), (中文(简体) ), 返回带有 `parsed` 包含已装入内容的密钥或一个 `error` 键,如果失败.

```js
const result = dotenv.config()

if (result.error) {
  throw result.error
}

console.log(result.parsed)
```

另外,还可以将选项传递给 `config`。 。 。 .

### 选项

#### 路径

默认 : `path.resolve(process.cwd(), '.env')`

如果您的文件包含环境变量, 您可以指定自定义路径 .

```js
require('dotenv').config({ path: '/custom/path/to/.env' })
```

#### 编码

默认 : `utf8`

您可以指定包含环境变量的文件的编码.

```js
require('dotenv').config({ encoding: 'latin1' })
```

#### 调试

默认 : `false`

您可以打开日志来帮助调试为什么某些密钥或值没有按照预期设置 .

```js
require('dotenv').config({ debug: process.env.DEBUG })
```

#### 多线

默认 : `default`

您可以指定值 `line-breaks` 将解析器切换为换行模式 允许在内部引用值.

```js
require('dotenv').config({ multiline: 'line-breaks' })
```

允许在此格式中指定多行值 :

```
PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIGT...
7ure...
-----END PRIVATE KEY-----"
```

确保数值以单引号或双引号字符开头,以同字符结尾.

## 解析

描述包含环境的文件内容的引擎 变量可供使用。 它接受字符串或缓冲,并将返回 带有已解析的密钥和值的对象.

```js
const dotenv = require('dotenv')
const buf = Buffer.from('BASIC=basic')
const config = dotenv.parse(buf) // will return an object
console.log(typeof config, config) // object { BASIC : 'basic' }
```

### 选项

#### 调试

默认 : `false`

您可以打开日志来帮助调试为什么某些密钥或值没有按照预期设置 .

```js
const dotenv = require('dotenv')
const buf = Buffer.from('hello world')
const opt = { debug: true }
const config = dotenv.parse(buf, opt)
// expect a debug message because the buffer is not in KEY=VAL form
```

### 规则

解析引擎目前支持以下规则:

-   `BASIC=basic` 变成 `{BASIC: 'basic'}`
    
-   跳过空行
    
-   线条开头 `#` 作为评论处理
    
-   空值变为空字符串( e)`EMPTY=` 变成 `{EMPTY: ''}`(中文(简体) )
    
-   内部引文保持不变(认为JSON)(`JSON={"foo": "bar"}` 变成 `{JSON:"{\"foo\": \"bar\"}"`(中文(简体) )
    
-   从未引用值的两端去除白空格(详见 [`trim`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/Trim)(中文(简体) )`FOO= some value` 变成 `{FOO: 'some value'}`(中文(简体) )
    
-   单取和双取的数值被省去(`SINGLE_QUOTE='quoted'` 变成 `{SINGLE_QUOTE: "quoted"}`(中文(简体) )
    
-   单取和双取值从两端保持空白(`FOO=" some value "` 变成 `{FOO: ' some value '}`(中文(简体) )
    
-   双引出值扩展出新行. 示例 `MULTILINE="new\nline"` 变成
    
    ```
    {MULTILINE: 'new
    line'}
    ```
    
-   如果使用 `{ multiline: "line-break" }` 选项. 在此模式下, 您不需要使用 `\n` 以区分行。 示例
    
    ```
    PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
    MIGT...
    7ure...
    -----END PRIVATE KEY-----"
    ```
    
    注意,在使用此选项时,所有以引用开头的值都必须以引用结尾.
    

## 财务问题

### 我是否应该承诺 `.env` 档案?

没有 我们 **强烈的** 建议不执行 `.env` 文件到版本 控制系统。 它只应包括数据库等环境特定值 密码或 API 密钥。 你的制作数据库应该有不同的 密码 .

### 我应该有多个 `.env` 档案?

没有 我们 **强烈的** 建议不使用“主” `.env` 文件和“环境” `.env` 类似文件 `.env.test`。您的配置应该因部署而异,不应该在环境之间分享价值.

> 在一个由12个要素组成的应用中,env vars是颗粒控制器,每个完全正交到其他env vars. 它们从未被归类为“环境”,而是在每次部署时得到独立的管理。 随着应用在一生中自然扩展为更多的部署,这个模型可以平稳地扩展.
> 
> – 说吧 – [十二因素应用程序](http://12factor.net/config)

### 已经设定的环境变量会发生什么?

我们永远不会修改任何已经设定的环境变量。 特别是,如果有变量 在你的 `.env` 文件与环境中已经存在的文件相撞,则该变量将被跳过。 这种行为可以让你超越所有 `.env` 具有机器特定环境的配置,尽管不推荐.

如果您想要覆盖 `process.env` 你可以做这样的事情:

```javascript
const fs = require('fs')
const dotenv = require('dotenv')
const envConfig = dotenv.parse(fs.readFileSync('.env.override'))
for (const k in envConfig) {
  process.env[k] = envConfig[k]
}
```

### 我可以自定义/写入多腾v的插件吗?

对于 `dotenv@2.x.x`对. `dotenv.config()` 现在返回一个代表对象 解析 `.env` 文档。 这给你所有需要继续的 设置值于 `process.env`。例如:

```js
const dotenv = require('dotenv')
const variableExpansion = require('dotenv-expand')
const myEnv = dotenv.config()
variableExpansion(myEnv)
```

### 那可变扩张呢?

尝试 [dotenv 扩展](https://github.com/motdotla/dotenv-expand)

### 我怎么用多腾夫 `import`? 吗?

ES2015及以后提供模块,允许您 `export` 任何顶级 `function`, (中文(简体) ), `class`, (中文(简体) ), `var`, (中文(简体) ), `let`,或 `const`。 。 。 .

> 当你运行一个包含 `import` 声明,它所导入的模块首先被加载,然后每个模块正体在依赖图的深度第一转弯中被执行,通过跳过任何已执行的来避免循环.
> 
> – 说吧 – [ES6 深度:模块](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/)

你必须跑 `dotenv.config()` 在引用任何环境变量之前。 以下是一个问题代码的例子:

`errorReporter.js`数字 :

```js
import { Client } from 'best-error-reporting-service'

export const client = new Client(process.env.BEST_API_KEY)
```

`index.js`数字 :

```js
import dotenv from 'dotenv'
import errorReporter from './errorReporter'

dotenv.config()
errorReporter.client.report(new Error('faq example'))
```

`client` 将无法正确配置,因为它是之前构建的 `dotenv.config()` 被处决。 有(至少)3种方法可以使这项工作发挥作用.

1.  预装多腾v : `node --require dotenv/config index.js` (单位:千美元)_说明:不需要 `import` 采用这种方法的dotenv_(中文(简体) )
2.  导入 `dotenv/config` 改为 `dotenv` (单位:千美元)_注意: 您不需要拨打 `dotenv.config()` ,并且必须使用这种方法通过命令行或环境变量传递选项_(中文(简体) )
3.  创建一个将执行的单独文件 `config` 一. 导言 [此评论关于 # 133](https://github.com/motdotla/dotenv/issues/133#issuecomment-255298822)

## 贡献指南

见 [捐款额](https://npmcn.com/package/%40cubejs-backend/dotenv/CONTRIBUTING.md)

## 更改日志

见 [变动情况](https://npmcn.com/package/%40cubejs-backend/dotenv/CHANGELOG.md)

## 谁在用道特活?

[这些 npm 模块依赖于它 .](https://www.npmjs.com/browse/depended/dotenv)

扩展它的项目经常使用 [npm 上的关键词"dotenv"](https://www.npmjs.com/search?q=keywords:dotenv)。 。 。 .

## 常见问题

### @cubejs-backend/dotenv 是什么？

从\.env 文件装入环境变量

### 如何安装 @cubejs-backend/dotenv？

在项目目录运行 npm install @cubejs-backend/dotenv，或使用 pnpm add / yarn add / bun add。

### @cubejs-backend/dotenv 支持 TypeScript 吗？

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

### @cubejs-backend/dotenv 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cubejs-backend/dotenv 需要什么版本的 Node\.js？

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

### @cubejs-backend/dotenv 可以商用吗？

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

### @cubejs-backend/dotenv 的下载量有多少？

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

### @cubejs-backend/dotenv 还在维护吗？

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