# @env-spec/parser 中文文档

规范地址：https://npmcn.com/package/%40env-spec/parser/

版本：0\.6\.3
npm 元数据更新时间：2026-11-13T02:26:08.573Z
中文译文更新时间：2026-11-13T18:44:33.104Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40env-spec/parser
原文对照：https://npmcn.com/package/%40env-spec/parser/?lang=original
项目主页：https://varlock.dev/
源码仓库：https://github.com/dmno-dev/varlock

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

- 包体积（解压后）：844 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2025-05-04T21:28:38.390Z
- 最新版本发布：2026-11-13T02:26:08.118Z
- 近 30 天下载量：46815（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 20 个）

## 中文简介

@env- spec 启用的多腾v 文件的解析器

## 安装

```sh
npm install @env-spec/parser
```

也可以使用：`pnpm add @env-spec/parser`、`yarn add @env-spec/parser`、`bun add @env-spec/parser`

## README

# `@env-spec`

> 我们正在积极寻找关于@env-spec的反馈. 请分享你的想法和想法 [RFC (RFC ) (法语)](https://github.com/dmno-dev/varlock/discussions/17)。 。 。 .

**@env- spec** 是一个简单的DSL/语言,可以扩展普通多腾v语法,允许您:

-   使用结构化元数据添加 `@decorator` 样式注释类似于 [联合来文文件](https://jsdoc.app/)
-   通过函数调用将设置值的语法正规化

_以下是一个简短的例子:_

```dotenv
# Stripe secret api key
# @required @sensitive @type=string(startsWith="sk_")
# @docs(https://docs.stripe.com/keys)
STRIPE_SECRET_KEY=fetchSecret("stripe/secret-key")
```

图书馆可以利用这种结构化数据提供:

-   额外的验证,强制,类型安全 您的env vars
-   处理过程中的额外护卫铁路 `@sensitive` 数据
-   没有附加应用程序代码或配置文件的更灵活的加载逻辑

## 如何使用计划数据?

这种计划信息在团队成员和机器之间共享时最有价值——所以它打算用于一个致力于git的文件中. 在大多数情况下,这将意味着建立一个 `.env.schema`,致力于源控制,其中包含所有计划信息以及可能的一些默认值. 这和拥有一个 `.env.example` file - 它只是更有用,并且实际上将它融入了env加载过程.

然后您可以使用设置值的附加文件 - 当然,它们可以添加附加项目或现有项目的压倒性 . 您是否想要使用单个 git- ignored `.env` 文档,或应用环境专用文件的级联(例如, `.env`, (中文(简体) ), `.env.local`, (中文(简体) ), `.env.test`等)由你决定. 然而,使用函数的新能力要求安全地解密数据,或者从外部来源装入值,意味着你可能会被诱惑使用承诺 `.env` 文档更多.

一个已启用的env spec工具将适当加载所有 env 文件, 合并了 schema 和 值, 以及从 shell/ process 读取的额外值 . 然后将采用可转换/填充值的图案,例如从外部来源解密或取出,以及实施强制和验证.

QQ 在一个非常简单的工程中,您也可以想象使用一个既包含计划又包含值的单个已承诺的.env文件,并利用函数调用来安全地加载敏感信息.

## 向后兼容

这个设计大多是向后兼容传统的.env文件,然而没有标准.env spec,各种工具的规则和特征略有不同,因此我们作出一些决定来尝试使事物标准化. 如果用户想要选择与其它工具相匹配的特定行为,工具可以支持额外的相容性标记.

扩展特性集指一个已启用的env spec spec parser将成功解析其他工具可能不会解析的env文件.

## 这是什么 _这个_ 包裹?

此软件包定义了用于解析的解析器和相关工具 **@env- spec** 启用了 .env 文件.  
它并没有提供任何经过这个解析步骤的东西——比如实际加载环境变量.  
在 .env 文件中实际使用的工具,请查看 [https://varlock.com (中文(简体) )](https://varlock.com/)

* * *

# 语言语法参考

这是关于env-spec语言本身细节的参考. 这里我们不假设特定装饰者的含义,或函数调用.

## 评论

Env- spec( 如 dotenv) 中的评论起始于 a `#`. 评论可以自行进行,也可以在某行行后进行.

-   `# this is a comment`
-   `KEY=val # so is this`
-   `# but this is invalid`

我们赋予这些评论更多的意义,让它们包含: `@decorators` 并把它们附在具体配置物品上.

### `Comment`

常规评论是一个不从 `@`

-   铅白空间是可选的 -- `#these`, (中文(简体) ), `# are`, (中文(简体) ), `# all valid`
-   里面的装饰被忽略了.. `# this @decorator is ignored`

### `DecoratorComment`

装饰者评论是一个以 `@` 并包含装饰器

-   它可能包含一个或多个装饰器 -- `# @type=integer`, (中文(简体) ), `# @sensitive @required`
-   在装饰者之后可能还会有额外的经常性评论 -- `# @sensitive=false # key is published in final build`

### `Divider`

分隔符是作为分隔符的注释,如水平行

-   以 `---` 或者说 `===` 被视为一个分隔符 -- `# ---`, (中文(简体) ), `# ===`
-   A 类 _单人_ 领导空白是可选的 -- `# ---`, (中文(简体) ), `#---`
-   之后的任何事情都被忽视和有效 -- `# --- some info`, (中文(简体) ), `# ------------`

### `CommentBlock`

评论块是一组连续的评论,不附在特定配置项上.

-   注释块以空行结束, a `Divider`,或文件的结尾.
-   两者 `DecoratorComment`s 和 `RegularComment`s 可能为相通

### `DocumentHeader`

如果有的话 `CommentBlock` 结尾为 `Divider` 作为文件的第一个要素,它将被视为标题.

-   此信头中的装饰器可用于配置所有包含的元素, 或者装入过程本身

## 装饰者

A 类 `Decorator` 用于在注释中附加特定配置项目或整个文档和加载过程的结构化数据.

-   每个装饰器都有一个名称和可选值 -- `@name=value`
-   只使用名称等于设置值为真 -- `@required` === `@required=true`
-   将使用通用的值处理规则解析装饰值(见下文)

**有效的装饰示例 :**

```dotenv
# @willBeTrue @willBeFalse=false @explicitTrue=true @undef=undefined
# @int=123 @float=123.456 @willBeString=123.456.789
# @quoted="with spaces" @trueString="true"
# @singleQuote='hi' @backTickQuote=`hi`
# @withNewline="new\nline"`
# @funcCallNoArgs=func() @dec=funcCallArray(val1, "val2") @dec=funcCallObj(k1=v1, k2="v2")
```

**无效的装饰示例 :**

```dotenv
# @
# @int=
# @spaceNeedsQuotes=spaces without quotes
# @noNewLines="new
#              laksdjf"
```

## 配置项目

配置项定义了单个的env vars. 每个都有一个密钥,一个可选值,以及可选的附加注释.

-   键必须从\[a-ZA-Z \]开始,然后是任何\[a-ZA-Z0-9 \] -- -- ++ `SOME_ITEM`时 `BAD-KEY`时 `2BAD_KEY`
-   不允许设置任何值, 将被视为 `undefined` - 说吧 `UNDEF_VAR=`
-   允许空字符串.. `EMPTY_STRING_VAR=""`
-   单行值可能以引号包裹,也可能不是,并将遵循共同的值处理规则(见下文)
-   多行值可能包含在其中之一 `( " | """ | ``` )`
-   只有评论 _直接_ 在该项目之前
-   不过a `Divider` 将会将上述注释分解为 `CommentBlock` 与项目无关
-   可在项目后另出评论 `ITEM1=foo # post comment`
-   后评论可以包含装饰器 `ITEM1=foo # @required`

## 行终

文件可能使用 `\n` 或者说 `\r\n` 线尾。 两者受到相同的对待,因此所分析的数值无论哪种方式都是相同的. 节点和语法错误位置( offset, line, 栏) 总是指您通过的内容, 包括任何 `\r` 字符键.

## 共同价值管理规则

对于配置项目值、装饰器值和函数调用参数内的值,对数值作类似的解释。 数值可能用引号包裹,也可能没有,但处理方式略有不同.

-   值可能永远不会包含实际的新行,但可能包含字符串 `\n`
-   如果数值不包含空格, 则不必用引号来包裹
-   未引用的值也可能不包含其他字符,视上下文而定:
    -   `ConfigItem` 值可能不包含 `[ #]`
    -   `Decorator` 值可能不包含 `[ #]`
    -   `FunctionCall` 参数可能不包含 `[ ,)]`
-   未引用的值将强制 `true`, (中文(简体) ), `false`, (中文(简体) ), `undefined` - 说吧 `@foo=false`
-   未引用的值会强制数字值 -- `@int=123 @float=123.456`
-   否则未引用的值将被视为字符串
-   引文中的值为 _永远_ 作为字符串处理 -- `@d1="with spaces" @trueString="true"`, (中文(简体) ), `@numStr="123"`
-   所有引用样式 ``[`'"]`` 没事了.. ``@dq="c" @bt=`b` @sq='a'``
-   与包装引用样式相匹配的已逃出引号是OK -- `@ok="escaped\"quote"`
-   在被引用的数值中,字符串 `\n` 将转换为实际新线

### 函数调用

如果一个值没有被引文所包裹, 并且看起来像一个函数调用 - 例如 `varlock(ASDF123...)` - 我们会把它解释为一个 `FunctionCall`。这与配置项目值和装饰值都相关.

-   函数名称必须从字母开始,然后可以包含字母、数字和下划线 `/[a-ZA-Z][a-ZA-Z0-9_]*/`
-   函数参数总是被解释为数组或对象
-   无法通过参数、单个值或多个值
-   或您可能通过密钥值对, 参数将被解释为对象
-   每个值将使用共同的值处理规则进行解释(见上文)

实例:

```dotenv
# @noArgs=fn()
# @oneArg=fn(asdf) @oneArgQuoted=fn("with quotes")
# @multipleArgs=fn(one, "two", three, 123.456)
# @objArgs=fn(key1=v1, key2="v2", key3=true)
```

* * *

## 与多滕v/多滕v-扩展/多滕vx的显著差异

-   我们不支持 _筑巢_ 默认扩展( ex : `VAR=${FOO:-${BAR}}`
    -   相反,你可以使用 `fallback` 直接函数 `VAR=fallback(ref(FOO), ref(BAR))`
-   我们不支持 _未回避_ 执行扩展范围内的引用( ex: `VAR="$(echo "foo")"`(中文(简体) )
    -   我们支持后置引用, 逃脱引用, 或者你可以使用 `exec` 直接函数 `VAR=exec(echo "foo")`
-   `$(...)` 扩展支持嵌入括号并引用 `)` (单位:千美元) `$(jq -r '.address|join(".")')`(中文(简体) )

* * *

## 本地 dev 和测试工作流程

-   `bun run dev` - 建造和观看一切
-   `bun run test` 构建全部, 运行测试, 并监视更改以重新运行
-   `bun run test:ci` 只要建立和运行测试一次

如果您需要通过额外的旗帜进行vitest( 例如运行特定的测试/ 文件) 运行 `bun run dev:grammar` 在一个终端和 `bunx vitest ...` 在另一个

设置 `PEGGY_TRACE=1` 将允许在 _已构建的语法文件_。 。 。 .

## 常见问题

### @env-spec/parser 是什么？

@env- spec 启用的多腾v 文件的解析器

### 如何安装 @env-spec/parser？

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

### @env-spec/parser 支持 TypeScript 吗？

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

### @env-spec/parser 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

### @env-spec/parser 可以商用吗？

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

### @env-spec/parser 的下载量有多少？

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

### @env-spec/parser 还在维护吗？

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