# @balena/compose-parser 中文文档

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

版本：1\.1\.0
npm 元数据更新时间：2026-11-11T04:14:01.692Z
中文译文更新时间：2026-11-11T04:14:48.639Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40balena/compose-parser
原文对照：https://npmcn.com/package/%40balena/compose-parser/?lang=original
项目主页：https://github.com/balena-io-modules/balena-compose-parser#readme
源码仓库：https://github.com/balena-io-modules/balena-compose-parser

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

- 包体积（解压后）：106 kB，28 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 22\.14\.0
- 运行依赖：4 个
- 首次发布：2025-09-10T07:12:13.653Z
- 最新版本发布：2026-11-11T04:14:01.237Z
- 近 30 天下载量：10880（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：87（近 12 个月 55 个）

## 中文简介

将 compose- go 包装到 解析 Balena- 兼容的 docker- compose. yml 文件

## 安装

```sh
npm install @balena/compose-parser
```

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

## README

# 巴拉纳- 组成- parser

围绕脚本打包 [编曲](https://github.com/compose-spec/compose-go) 解析并验证 Docker 编译用于 Balena 应用程序的文件.

## 概览

该项目提供了一个Node.js库,它使用Go 二进制(由作曲-go所建)来解析多克作曲文件并使它们与balena相通使用. 它处理:

-   解析标准 Docker 编译文件
-   验证具体巴莱纳的限制
-   将作曲配置转换为相容巴莱纳格式
-   将构件转化为建筑物/推土机图像描述符

## 所需资源

-   节点.js 20+
-   Go 1.24+(用于当地建筑)

## 安装

```
npm i @balena/compose-parser
```

## 建筑

该项目由两个主要部分组成:

1.  **前进二进制** (单位:千美元)`lib/main.go`:环绕作曲的包装器,输出结构化的JSON
2.  **类型脚本库** (单位:千美元)`lib/`: 调用 Go 二进制和处理结果的 Node.js 库

## 大楼

```bash
# Build everything
npm run build

# Build Go binary only
npm run build:go
```

## 测试

### 单位测试

```bash
npm run test
```

运行 TypeScript 单元测试,直接测试库功能. 这不涵盖全部功能,因为由于CI的限制,使用Go二进制的测试在多克进行.

### 整合测试

```bash
npm run test:compose

# Or the following if running build:go first:
npm run test:integration
```

集成测试验证了剖析输入编解文件的编解-去包装器的功能. `npm run test:compose` 用于在 Docker 中运行测试,但如果一个构建的 Go 二进制可用,则可以直接运行测试 `npm run build:go`。 。 。 .

## 开发脚本

```bash
# Check for linting issues
npm run lint

# Fix auto-fixable linting issues
npm run lint-fix
```

## API 密码

### 基本用途

```typescript
import { parse, defaultComposition, toImageDescriptors } from '@balena/compose-parser';

// Parse a compose file
const composition = await parse('docker-compose.yml');

// Parse multiple compose files (later files override earlier ones)
const composition = await parse([
  'docker-compose.yml', 
  'docker-compose.override.yml'
]);

// Convert composition to image descriptors for building/pulling
const imageDescriptors = toImageDescriptors(composition);
```

### 分析选项

默认 `parse()` 在您命名的作曲文件外, 读取任何文件 。 不是这个 进程的环境,而不是 `env_file`, (中文(简体) ), `label_file`, (中文(简体) ), `include` 或者说 `extends.file`。 。 。 .

```typescript
// Written by whoever is running this process
const trusted = await parse('docker-compose.yml', { hostEnvironment: true });

// Someone else's file. Keep the defaults, and skip interpolation if it has been
// interpolated already
const untrusted = await parse('docker-compose.yml', { skipInterpolation: true });
```

| 选项 | 默认 | 生效时 |
| --- | --- | --- |
| `hostEnvironment` | `false` | `${VAR}` 和无值 `environment` 从此进程环境中解析条目,以及 `env_file`, (中文(简体) ), `label_file`, (中文(简体) ), `include` 财务报告和审定财务报表 `extends.file` 被跟踪并折叠入 |
| `skipInterpolation` | `false` | `${VAR}` 参考文献为左逐字记录 |

两种选择涵盖不同的东西,这就是为什么它们是分开的.

```yaml
environment:
  - SOME_VARIABLE              # valueless, resolved by name, hostEnvironment
  - OTHER=${SOME_VARIABLE}     # substitution, skipInterpolation
```

替换仍然发生在默认情况下, 相对于空环境,所以 `${VAR}` 成为空字符串,同时 `${VAR:-fallback}` 给它的倒置. 这使得一个写作文件 围绕默认工作.

`hostEnvironment` 也允许二次文件, 并且没有限制其位置 点。 一个不信任的文件可以命名此进程可以读取的任何路径, 包括 `/proc/<pid>/environ`留下它就是 保持解析的药效.

两种默认在 v1. 0. 0 之前有效, 所以一个呼叫者依赖其中之一 现在必须这么说.

### 序列化

`serialize()` 写一个解析成单自成一体的成分 `docker-compose.yml`。与上面的解析选项对等以移动一个作曲 从一个能够解决它的机器到一个不能尝试的机器.

```typescript
import * as fs from 'node:fs/promises';
import { parse, serialize } from '@balena/compose-parser';

// On the user's machine: resolve everything against their environment and files
const composition = await parse('docker-compose.yml', { hostEnvironment: true });
await fs.writeFile('folded.yml', serialize(composition));

// On the builder: re-read it without touching the environment or the filesystem
const reparsed = await parse('folded.yml', { skipInterpolation: true });
// deep-equals `composition`
```

输出没有 `env_file`, (中文(简体) ), `label_file`, (中文(简体) ), `include` 或者说 `extends`,从 `parse()` 已经叠入.

无论读取输出 **必须** 分析一下 `skipInterpolation: true`。 。 。 . 数值已经插入到第一个剖析中,a `$` 还在 输出是字面意思;再次插入会改变它,或从 读者自己的环境.

在视窗上, `serialize()` 写入 `build.context` 与 `/` 分离器,以及 如果上下文位于与作曲文件不同的驱动器上,则丢出.

### 图像描述符

这个 `toImageDescriptors()` 函数将一个构成转换为可用于图像操作的描述符 :

```typescript
const descriptors = toImageDescriptors(composition);
// Returns array of:
// {
//   serviceName: string,
//   image: string | BuildConfig,
//   contract?: ContractObject  // if service has contract requirement labels
// }
```

## 巴莱纳特定地物

### 合同标签

支持验证合同要求标签:

-   `io.balena.features.requires.sw.supervisor`: 主管版本的 semver 范围
-   `io.balena.features.requires.hw.device-type`: 设备类型
-   `io.balena.features.requires.arch.sw`: 建筑(`aarch64`, (中文(简体) ), `amd64`, (中文(简体) ), `armv7hf`页:1
-   `io.balena.features.requires.sw.l4t`: L4T 版本范围

## 常见问题

### @balena/compose-parser 是什么？

将 compose- go 包装到 解析 Balena- 兼容的 docker- compose\. yml 文件

### 如何安装 @balena/compose-parser？

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

### @balena/compose-parser 支持 TypeScript 吗？

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

### @balena/compose-parser 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

### @balena/compose-parser 可以商用吗？

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

### @balena/compose-parser 的下载量有多少？

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

### @balena/compose-parser 还在维护吗？

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