# @basenative/doppler 中文文档

规范地址：https://npmcn.com/package/%40basenative/doppler/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:48:18.447Z
中文译文更新时间：2026-10-31T15:56:49.698Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basenative/doppler
原文对照：https://npmcn.com/package/%40basenative/doppler/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/doppler#readme
源码仓库：https://github.com/DuganLabs/BaseNative

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

- 包体积（解压后）：38 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-18T05:29:07.937Z
- 最新版本发布：2026-10-31T13:48:18.140Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

围绕多普勒的瘦开发人员体验层-本地开发包装器，CI助手，项目引导，环境验证。BaseNative ship plumbing, never values。

## 安装

```sh
npm install @basenative/doppler
```

也可以使用：`pnpm add @basenative/doppler`、`yarn add @basenative/doppler`、`bun add @basenative/doppler`

## README

# @basenative /多普勒

> 管道，而不是价值观。BaseNative为每个项目提供相同的多普勒工作流程；多普勒掌握着真正的秘密。

之上的一个瘦的、无依赖的开发人员体验层 [多普勒](https://www.doppler.com/) CLI。让每个DuganLabs repo (`basenative`， `duganlabs`， `greenput`， `pendingbusiness`， `ralph-station`， `t4bs`， `warren-sys`， `warrendugan`)引导，验证，并运行多普勒完全相同的方式。

## 边界规则

> BaseNative只提供管道。 **它从不读取、存储或传输值。**

这个包中的每个命令都输出为 `doppler` 为了真正的工作。CLI的存在是为了使跨项目的工作流保持一致，而不是充当自己的秘密存储库。

## 安装

```bash
# Per-project
pnpm add @basenative/doppler

# The doppler CLI is a system dependency, not an npm dep:
brew install dopplerhq/cli/doppler         # macOS
curl -Ls --tlsv1.2 https://cli.doppler.com/install.sh | sh   # Linux
scoop install doppler                       # Windows

doppler login                                # one time
```

## 一次性项目设置

```bash
bn-doppler init my-app
```

这将:

1.  创建一个名为 `my-app`.
2.  创建配置 `dev`， `prep`， `prod`.
3.  将本地回购钉在 `dev` 配置(`doppler setup`）。
4.  放下启动器 `doppler-required.json` 进入回购根目录。

编辑 `doppler-required.json` 要声明应用程序需要哪些秘密：

```json
{
  "secrets": [
    { "name": "DATABASE_URL",   "required": true },
    { "name": "SESSION_SECRET", "required": true },
    { "name": "SENTRY_DSN",     "required": false }
  ],
  "configs": ["dev", "prep", "prod"]
}
```

然后通过仪表板或CLI设置值：

```bash
doppler secrets set DATABASE_URL
doppler secrets set SESSION_SECRET
```

## 本地开发工作流程

```bash
# Recommended in your repo's package.json scripts:
{
  "dev":   "doppler run -- pnpm exec bn-wrangler pages dev dist",
  "build": "doppler run -- pnpm build"
}

# Or via the wrapper:
bn-doppler run -- pnpm dev
```

就是这样。否 `.env` 文件。不要意外泄露秘密。如果缺少一个秘密，应用程序会在启动时得到一个快速的，特定的错误 `requireSecrets`.

## CI/CD接线（GitHub Actions）

```bash
# Once, locally:
bn-doppler ci-token --config prod
# (it asks for confirmation, then prints the token)

# Add it to the repo:
gh secret set DOPPLER_TOKEN --body "<paste>"
```

然后在 `.github/workflows/deploy.yml` (全文载于 `templates/.github-actions-doppler-snippet.yml`):

```yaml
- uses: dopplerhq/cli-action@v3

- name: Verify Doppler secrets
  env: { DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }} }
  run: pnpm exec bn-doppler verify --config prod

- name: Deploy
  env: { DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }} }
  run: doppler run --config prod -- pnpm exec bn-wrangler deploy
```

## `bn-doppler verify`

反复试验 `doppler-required.json` 对比实际的多普勒配置：

```bash
bn-doppler verify --config dev
# OK — all 3 required secret(s) are populated in config "dev".
```

如果缺少任何东西，它将退出非零状态，并准确地打印缺少的名称——作为部署前CI的第一步是完美的。

## 编程API

```js
import {
  dopplerRun,
  requireSecrets,
  injectIntoWrangler,
  MissingSecretsError,
} from '@basenative/doppler';
import { loadRequired, findMissing } from '@basenative/doppler/required';

// Boot-time check (after `doppler run -- node ./server.js` injects env vars):
await requireSecrets(['DATABASE_URL', 'SESSION_SECRET']);

// Or pull straight from Doppler:
await requireSecrets(['DATABASE_URL'], {
  source: 'doppler',
  project: 'my-app',
  config: 'prod',
});

// Split resolved values into vars vs secrets for Wrangler:
const { vars, secrets } = injectIntoWrangler({
  env: process.env,
  names: ['APP_NAME', 'API_TOKEN', 'SESSION_SECRET'],
});

// Or run a child process under doppler:
await dopplerRun(['pnpm', 'build'], { config: 'prod' });
```

## 为什么会出现这种模式

-   **每个项目都有一个剧本。** `doppler run -- pnpm dev` 同样的道理 `basenative`， `t4bs`， `greenput`等。
-   **否 `.env` 漂移。** 本地开发，预览和prod都从相同的规范多普勒配置中读取。
-   **CI审核。** 一个 `DOPPLER_TOKEN` 而不是17个单独的秘密。
-   **引导时快速失败。** `requireSecrets` 将凌晨3点的生产页面转换为上午9点的红色CI运行。
-   **BaseNative中没有值。** 这个包裹是管道，所有真正的秘密都在多普勒，就这样。

## 链接

-   碱性单氧- [https://github.com/DuganLabs/basenative](https://github.com/DuganLabs/basenative)
-   问题- - - - - - [https://github.com/DuganLabs/basenative/issues](https://github.com/DuganLabs/basenative/issues)
-   文档- [https://github.com/DuganLabs/basenative#readme](https://github.com/DuganLabs/basenative#readme)

## 许可证

apache - 2.0

## 常见问题

### @basenative/doppler 是什么？

围绕多普勒的瘦开发人员体验层-本地开发包装器，CI助手，项目引导，环境验证。BaseNative ship plumbing, never values。

### 如何安装 @basenative/doppler？

在项目目录运行 npm install @basenative/doppler，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bn-doppler，可以用 npx bn-doppler 直接运行。

### @basenative/doppler 支持 TypeScript 吗？

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

### @basenative/doppler 支持 ESM 还是 CommonJS？

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

### @basenative/doppler 可以商用吗？

@basenative/doppler 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basenative/doppler 还在维护吗？

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