# @b9g/libuild 中文文档

规范地址：https://npmcn.com/package/%40b9g/libuild/

版本：0\.2\.31
npm 元数据更新时间：2026-11-02T20:38:56.793Z
中文译文更新时间：2026-11-07T17:26:11.179Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40b9g/libuild
原文对照：https://npmcn.com/package/%40b9g/libuild/?lang=original
项目主页：https://github.com/bikeshaving/libuild#readme
源码仓库：https://github.com/bikeshaving/libuild

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

- 包体积（解压后）：236 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.10\.0
- 运行依赖：7 个
- peer 依赖：playwright ^1\.40\.0，typescript ^5\.0\.0 \|\| ^6\.0\.0
- 首次发布：2025-10-26T17:14:18.802Z
- 最新版本发布：2026-11-02T20:38:56.524Z
- 近 30 天下载量：3658（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 46 个）

## 中文简介

新建零配置库

## 安装

```sh
npm install @b9g/libuild
```

也可以使用：`pnpm add @b9g/libuild`、`yarn add @b9g/libuild`、`bun add @b9g/libuild`

## README

# 闲置

零配置库与ESBuild相建.

Libuild 是 JavaScript/ TypeScript 库的构建工具,用于发布到 国家预防机制。 它解决了无害环境管理/CJS支持,类型生成,并生产了干净的软件包 和消费者所需要的文件和配置.

## 安装

```bash
npm install -D @b9g/libuild
bun add -d @b9g/libuild
```

## 使用量

```bash
# Build your library (development mode - no package.json changes)
libuild build

# Build and update package.json for npm link
libuild build --save

# Build and publish to npm
libuild publish
```

## 特征

-   **无配置** - 源文件和标准包。 json是您需要的
-   **多种格式** - 支持无害环境管理、CJS、UMD和生成 d.ts 文件
-   **清洁输出** - 只有必要的文件和字段进入软件包
-   **有利于发展** - 国家防范机制的链接只是工作,变革可以保存到软件包

## 公约=配置

### 条目点

-   **图书馆模块**: 所有顶级 `.js`编号 :`.ts` 文件在 `src/` (不包括 `_` 前缀文件)
-   **工人**页:1 `src/<name>.worker.ts` 建为 `dist/<name>.worker.js` 但没有 `exports`。它是通过文件路径加载的代码 - `new Worker(new URL("./decode.worker.js", import.meta.url), {type: "module"})` - 从不通过出口地图, 所以没有什么可以公开的。 仅限无害环境管理.
-   **CLI 二进制**: 任何引用于 `package.json` `bin` 字段被编译为独立的可执行文件
-   **UMD 构建**: 如果 `src/umd.ts` ,创建与浏览器兼容的 UMD 构建

### 输出结构

-   **平面输出**数字 : `src/index.ts` → `dist/index.js` - 在软件包根部发布模块,因此直接CDN URL类似 `cdn.jsdelivr.net/npm/<pkg>/index.js` 只是工作时
-   **可执行文件**数字 : `bin/cli.ts` → `dist/bin/cli.js` (bin/ 保留为子目录)
-   **无害环境管理**数字 : `.js` 有ES模块语法的文件
-   **常见JS**数字 : `.cjs` 节点.js兼容性的文件
-   **类型脚本**数字 : `.d.ts` 所有模块的申报文件( 当 TypeScript 可用时); 内部模块随导入件完整地迁移
-   **模块增强**数字 : `declare module` 块在.d.ts输出中保存
-   **代码分割**: 动态导入在 `dist/_chunks/`
-   **干净的包裹**: 为消费者优化(无 Dev 脚本)

### 格式控件

-   **仅限无害环境管理**: 删除 `main` 从 package.json 跳过 CommunityJS 构建
-   **常见JS 检测**时间: `main` 字段启用 `.cjs` 正在建设
-   **UMD 构建**页:1 `src/umd.ts` 用于与浏览器兼容的构建

### 导出异名

-   **遗产支助**数字 : `./entry.js` 自动化名为 `./entry`
-   **软件包.json**: 总是导出为 `./package.json`
-   **自定义导出**: 保留并增强现有的成套出口

### 软件包.json 转换

-   **开发模式** (默认):根包.json不变,无出息
-   **\--保存模式**: Root 软件包.json 更新到指向 `./dist/*` npm 链接的文物
-   **Dist 软件包。 json**: 清洁的消费者准备版本,有根相通的路径
-   **连接路径**: 自动转换自 `src/` 建筑文物参考文献
-   **出口领域**: 为所有切入点生成, 并按适当类型顺序排列

## 实例

### 简单库

鉴于这一结构:

```
src/
  index.ts
  utils.ts
  _internal.ts  # ignored (underscore prefix)
```

生产:

```
dist/
  index.js         # ESM
  index.cjs        # CommonJS
  index.d.ts       # TypeScript declarations
  utils.js
  utils.cjs
  utils.d.ts
  package.json     # Clean consumer version
```

### 带有 CLI 的图书馆

```
package.json:
{
  "bin": { "mytool": "src/cli.js" }
}

src/
  index.ts
  cli.ts
```

生产:

```
dist/
  index.js
  index.cjs
  index.d.ts
  cli.js           # Compiled CLI (dual-runtime shebang, executable)
  cli.cjs
  cli.d.ts
  package.json     # bin: { "mytool": "cli.js" }
```

### EME 仅存库

仅建立无害环境管理(无普通JS),删除 `main` 字段 :

```json
// package.json
{
  "name": "my-lib",
  "module": "dist/index.js",  // ESM entry
  "types": "dist/index.d.ts"
  // no "main" field = no CJS
}
```

生产:

```
dist/
  index.js         # ESM only
  index.d.ts
  utils.js         # ESM only
  utils.d.ts
  package.json     # ESM-only exports
```

### 带有 UMD 的多格式

```
src/
  index.ts
  utils.ts
  umd.ts         # Browser build entry
```

生产:

```
dist/
  index.js
  index.cjs
  index.d.ts
  utils.js
  utils.cjs
  utils.d.ts
  umd.js           # UMD browser build
  package.json
```

### 生成软件包。 json 出口

**双格式** (ESM + CommunityJS): (中文(简体) )

```json
{
  "main": "index.cjs",
  "module": "index.js",
  "types": "index.d.ts",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "import": "./index.js",
      "require": "./index.cjs"
    },
    "./utils": {
      "types": "./utils.d.ts",
      "import": "./utils.js",
      "require": "./utils.cjs"
    },
    "./utils.js": {
      "types": "./utils.d.ts",
      "import": "./utils.js",
      "require": "./utils.cjs"
    },
    "./package.json": "./package.json"
  }
}
```

**仅限无害环境管理** (无) `main` 字段中的字段 :

```json
{
  "module": "index.js",
  "types": "index.d.ts",
  "type": "module",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "import": "./index.js"
    },
    "./utils": {
      "types": "./utils.d.ts",
      "import": "./utils.js"
    },
    "./utils.js": {
      "types": "./utils.d.ts",
      "import": "./utils.js"
    },
    "./package.json": "./package.json"
  }
}
```

**Root 软件包.json** (与 -- 保存):

```json
{
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}
```

## 图标

### `libuild build` (默认)

以开发模式构建您的库 :

-   将所有切入点编译为多种格式
-   生成类型脚本声明
-   创建优化软件包.json 文件
-   保护根包.json(无基特噪声)

### `libuild build --save`

构建并更新根包. json for npm link :

-   一切从 `libuild build`
-   更新根包. json 指向 Dist 文物
-   适合测试 `npm link`

### `libuild publish`

构建并发布到 npm :

-   用 -- save 运行完整的构建
-   如果根包. json 不是私人的警告
-   从 dist 目录中以干净的软件包发布. json

## 所需资源

-   **节点.js 20.10+** 或者说 **1.0+号舱** (为跑来跑去)
-   **类型脚本** (可选,用于.d.ts生成)
-   对图书馆消费者没有运行时间要求

## 测试 : `libuild test`

运行您的套房, 包含一个命令和一组测试文件 :

```sh
libuild test                        # bun, current directory
libuild test tests -p bun -p node   # both runtimes
libuild test -p deno                # deno, via `deno test`
libuild test -p chromium            # real browser via Playwright
libuild test path/to/one.test.ts    # single-file loop
```

Deno 通过自己的文件运行相同的文件 `deno test`,哪些桥 `node:test` ,所以不需要Deno特定的测试API,摘要在所有三个运行时间读取相同.

导入便携式 API 从 `@b9g/libuild/test` (单位:千美元)`describe`编号 :`test`编号 :`it`编号 :`expect`钩子, `test.concurrent`, (中文(简体) ), `.each`交叉运行时间 `toMatchSnapshot`) (中文(简体) ). 文件运行于每个文件孤立的进程中,其依赖性由您解决 `node_modules`· ; `import.meta.url`编号 :`.dirname`编号 :`.filename` 财务报告和审定财务报表 `__dirname`编号 :`__filename` 指向源文件,而不是捆绑.

旗帜 : `--timeout <ms>` 是每个文件的预算,在包子上,它也作为每测试的超时应用(bun默认为每测试5s;没有这个,缓慢的测试在文件预算事项之前死亡). `--concurrency <n>` 盖住一次运行的文件数量——降低为测试产生自己过程的套房. `--filter <glob>` 选择文件; `-u` 更新快照; `--debug` 保持浏览器打开并保存捆绑目录.

### 覆盖范围

`libuild test --coverage -p node` 收集节点的覆盖,并在运行后打印一个表格,通过捆绑的源地图将行图映射回您的源文件. `--coverage-reporter lcov html` 选择 c8 的记者( 默认) `text`; 文件报告到 `coverage/`,或 `--coverage-dir <dir>`。测试文件和声明文件被排除在外。 覆盖只有节点:bun不会为捆绑而写出V8覆盖,而deno则会写出自己的格式,因此在这些运行时间上会像往常一样运行并收不到任何东西.

### 内源测试

测试可以停留在它们覆盖的模块, Rust的方式 `mod tests` 已经 他们 共享模块的关闭, 这样他们就可以到达帮助者 并声明从不 导出 :

```ts
const SEEN = new Map<string, number>();

function memoKey(a: number, b: number) { return `${a}:${b}`; }

export function addMemo(a: number, b: number) {
  const key = memoKey(a, b);
  if (SEEN.has(key)) { return SEEN.get(key)!; }
  const out = a + b;
  SEEN.set(key, out);
  return out;
}

if (import.meta.litest) {
  const {test, expect} = import.meta.litest;

  test("memoizes", () => {
    expect(addMemo(1, 2)).toBe(3);
    expect(SEEN.get(memoKey(1, 2))).toBe(3);   // never exported
  });
}
```

没有什么可导入的 : `import.meta.litest` **实值** 测试 API, 相同 表面 `@b9g/libuild/test` 出口. `libuild test` 注射并运行这些 文档与您的 `*.test.*` 套件; 任何文件 `src/` 内含 警卫被发现了.

`libuild build` 完全去除块 —— 断言和任何导入 只需要测试 公布的软件包没有显示测试内容 消费者不需要安装libear来装入你的图书馆.

有两件事值得了解:

-   **把警卫写成 `if (import.meta.litest)`。 。 。 .** 寻找的正是发现 所以,一个测试块 后面不同的表达 从建筑剥离 但永远不要跑.
-   **包含内源测试的文件在 `dist`** (单位:千美元)`if`编号 :`continue` 崩溃到 `||`,等等). 移除块需要不断折叠, 用于每个文件的 libuild 而不是打开整个构建 因此,没有内源测试的模块保持字节-等同输出.

同一个守卫门 测试唯一的代码 不是测试。 一个在测试中在框架循环中运行的支票, 并且不能飞船, 坐到后面 `if (import.meta.litest)`:在每一个测试捆绑中,表达式是测试 API,所以检查运行;在构建中它是 `undefined` 被保护的密码被剥去, 只有它称之为功能就随之而来.

对于 TypeScript , 将 libuild 的环境声明添加到您的 `tsconfig.json`数字 :

```json
{"compilerOptions": {"types": ["@b9g/libuild/litest.d.ts"]}}
```

运行时注释 :

-   **包子不能筑巢 `test()` 内部 `test()`** (oven-sh/bun#5900) (英语). 值得注意的是,ESLint公司 `RuleTester` 登记嵌入子测试,所以规则套房被击中 `NotImplementedError` 包子上 要么用 `-p node`,或平地规则测试器的钩子(`RuleTester.describe = (_n, fn) => fn()` 以保持便携式.
-   libuild 仅为无害环境管理: 软件包声明 `"type": "commonjs"` 拒绝(无包装) `type` 字段是罚款的)。 CJS只作为建筑生产 `main`\-菲尔德倒下.

## 许可证

麻省理工学院

## 常见问题

### @b9g/libuild 是什么？

新建零配置库

### 如何安装 @b9g/libuild？

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

### @b9g/libuild 支持 TypeScript 吗？

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

### @b9g/libuild 支持 ESM 还是 CommonJS？

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

### @b9g/libuild 需要什么版本的 Node\.js？

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

### @b9g/libuild 可以商用吗？

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

### @b9g/libuild 的下载量有多少？

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

### @b9g/libuild 还在维护吗？

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