# @amccarthy1/typed-env 中文文档

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

版本：1\.3\.0
npm 元数据更新时间：2024-06-05T18:10:08.448Z
中文译文更新时间：2026-11-06T00:11:47.156Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：36.2 kB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-05-01T20:49:23.100Z
- 最新版本发布：2024-06-05T18:10:08.281Z
- 近 30 天下载量：9772（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

类型环境变量

## 安装

```sh
npm install @amccarthy1/typed-env
```

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

## README

# 输入信封

[![codecov](https://codecov.io/gh/amccarthy1/typed-env/branch/main/graph/badge.svg?token=MA2UGQG274)](https://codecov.io/gh/amccarthy1/typed-env)

Typescript 的强型, 0 依赖性环境变量解析器 !

## 开始吧

```bash
npm install --save @amccarthy1/typed-env  # npm
```

```bash
yarn add @amccarthy1/typed-env  # yarn
```

```ts
import { TypedEnv, EnumVar } from '@amccarthy1/typed-env'

const env = TypedEnv({
  ENVIRONMENT: EnumVar({ options: ['dev', 'staging', 'prod'] }),
})

doWhateverToRunApp(env.ENVIRONMENT) // env.ENVIRONMENT is of type 'dev' | 'staging' | 'prod'
```

## 为什么这样有用

许多服务使用环境变量进行运行时配置, 任何来自当前 环境或记录动词, 给像 API 密钥和秘密的东西。 但很多次,这些 环境变量未经验证,在需要时天真地从字符串中解析出.

此库旨在允许您以更安全的方式定义环境变量 。 拿着这个 示例:

```ts
const environment = process.env.ENVIRONMENT

const makePayment = (amount: bigint) => {
  if (environment === 'prod') {
    makeRealPayment(amount)
  } else {
    makeMockPayment(amount)
  }
}
```

如果您配置了您的服务器 `ENVIRONMENT=production` 改为 `ENVIRONMENT=prod`? 吗? 突然间,所有的用户都得到了免费产品 因为你在做模拟支付而不是 真实的!

如果你用TypedEnv代替, 你会得到这个

```ts
const env = TypedEnv({
  ENVIRONMENT: EnumVar({ options: ['dev', 'staging', 'production'] }),
})

const makePayment = (amount: bigint) => {
  if (env.ENVIRONMENT === 'prod') {
    // TypeError!
    // `This condition will always return 'false' since
    // the types '"dev" | "staging" | "production"' and
    // '"prod"' have no overlap.`
    return makeRealPayment(amount)
  } else {
    return makeFakePayment(amount)
  }
}
```

## 支持哪些类型?

目前, 字符串、 enum、 整数、 布尔和日期都被支持, 尽管您可以定义自己的自定义类型 使用 `Declaration<T>` 类型

```ts
export type Declaration<T> = {
  variable?: string // The name of the environment variable; defaults to match the key if not specified
  parser: Parser<T> // A function (value: string) => T
}
```

## 可选变量呢?

TypedEnv 主要是为需要的变量而构建的,但确实支持使用一个 `defaultValue` 属性. 如果您不想使用明确的默认, 您可以使用 `optional()` 提供了自动包装 输入默认值为 `null` 转换 a `Declaration<T>` 改为 `Declaration<T|null>`

```ts
const env = TypedEnv({
  required: BoolVar({ defaultValue: false }),
  optional: optional(BoolVar()),
})
// This schema yields the following type object
const env: {
  required: boolean
  optional: boolean | null
}
```

一般倾向于使用 `defaultValue` 超过 `optional` 包装,但是 `optional` 可能有益于移徙 已有的将 env vars 视为可选的编码库.

## 常见问题

### @amccarthy1/typed-env 是什么？

类型环境变量

### 如何安装 @amccarthy1/typed-env？

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

### @amccarthy1/typed-env 支持 TypeScript 吗？

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

### @amccarthy1/typed-env 支持 ESM 还是 CommonJS？

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

### @amccarthy1/typed-env 可以商用吗？

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

### @amccarthy1/typed-env 的下载量有多少？

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

### @amccarthy1/typed-env 还在维护吗？

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