# @basenative/wrangler-preset 中文文档

规范地址：https://npmcn.com/package/%40basenative/wrangler-preset/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:08.684Z
中文译文更新时间：2026-10-31T16:19:07.981Z
软件包许可：Apache-2\.0

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

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

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

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

## 中文简介

固定牧马人版本键入牧马人.Pin一次，每个项目一起移动。

## 安装

```sh
npm install @basenative/wrangler-preset
```

也可以使用：`pnpm add @basenative/wrangler-preset`、`yarn add @basenative/wrangler-preset`、`bun add @basenative/wrangler-preset`

## README

# @basenative / wrangler-preset

> 一次别针，每个项目一起移动。

一个固定的 [牧马人](https://developers.cloudflare.com/workers/wrangler/) Version加上一个小的，无依赖的片段生成器 `wrangler.toml`。旨在保持每个DuganLabs的repo (`basenative`， `duganlabs`， `greenput`， `pendingbusiness`， `ralph-station`， `t4bs`， `warren-sys`， `warrendugan`) 同时在同一牧马人身上。

## 为什么存在这个

在整个组织中，项目的牧马人版本从 `^3.114` 来 `^4.85`。漂移原因:

-   不一致 `compatibility_date` 语义。
-   不同的默认值 `nodejs_compat` 和朋友们。
-   每个回购重新决定如何连接D1 / KV / R2。
-   牧马人升级的痛苦持续了数周。

这个包固定了一个Wrangler版本，公开了一组推荐的标志，并附带了一个小的、有类型的构建器，因此每个repo中的配置看起来都是一样的。

## 安装

```bash
pnpm add @basenative/wrangler-preset
# wrangler is pulled in transitively at the version this preset pins.
```

你不再需要一个直接 `wrangler` 在你的回购依赖。使用 `bn-wrangler` (或 `pnpm exec bn-wrangler`)，你总是会得到固定的版本。

## 命令行界面

```bash
# Pinned wrangler — pass through any wrangler args:
bn-wrangler --version
bn-wrangler pages dev dist
bn-wrangler deploy
bn-wrangler d1 migrations apply DB --remote

# Preset diagnostics:
bn-wrangler --bn-version
bn-wrangler --bn-help
```

## 编程API

### `defaults`

推荐的基线。将其扩展到你的配置中：

```js
import { defaults, mergeWrangler, toToml } from '@basenative/wrangler-preset';

const config = mergeWrangler(
  { name: 'my-app', main: 'src/index.js' },
  defaults,
);

console.log(toToml(config));
```

### `bindings.d1(name, dbName, dbId)` / `kv(name, id)` / `r2(name, bucket)` / `do(name, className, scriptName?)`

每个返回一个小片段对象，你可以 `mergeWrangler(...)` 到一个配置:

```js
import { defaults, bindings, mergeWrangler, toToml } from '@basenative/wrangler-preset';

const cfg = mergeWrangler(
  { name: 'my-app', main: 'src/index.js' },
  defaults,
  bindings.d1('DB', 'my-app-db', '<uuid>'),
  bindings.kv('CACHE', '<kv-id>'),
  bindings.r2('ASSETS', 'my-app-assets'),
  bindings.do('ROOM', 'Room'),
);

await fs.writeFile('wrangler.toml', toToml(cfg));
```

### `mergeWrangler(base, ...frags)`

深度合并标量 (稍后获胜) 并连接表数组 (`d1_databases`， `kv_namespaces`， `r2_buckets`， `durable_objects.bindings`）。

### `toToml(config)`

零依赖TOML序列化器覆盖了Wrangler使用的子集：标量、标量的数组、表和表的数组。

## 从模板生成

```bash
cp node_modules/@basenative/wrangler-preset/templates/wrangler.toml.tmpl wrangler.toml
# then edit __PROJECT_NAME__ etc.
```

## 采用检查表（每个回购）

1.  移除任何直接 `wrangler` 来自回购的dep `package.json`.
2.  `pnpm add @basenative/wrangler-preset`.
3.  取代直接 `wrangler ...` 在脚本中调用 `bn-wrangler ...`.
4.  集 `compatibility_date` 从 `defaults.compatibility_date` (或复制模板)。
5.  通过升级此软件包将所有人聚集在一起: 每个季度一个PR，而不是八个。

## 链接

-   碱性单氧- [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/wrangler-preset 是什么？

固定牧马人版本键入牧马人\.Pin一次，每个项目一起移动。

### 如何安装 @basenative/wrangler-preset？

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

### @basenative/wrangler-preset 支持 TypeScript 吗？

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

### @basenative/wrangler-preset 支持 ESM 还是 CommonJS？

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

### @basenative/wrangler-preset 可以商用吗？

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

### @basenative/wrangler-preset 还在维护吗？

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