# @balena/dockerignore 中文文档

规范地址：https://npmcn.com/package/%40balena/dockerignore/

版本：1\.0\.2
npm 元数据更新时间：2026-01-20T12:07:36.255Z
中文译文更新时间：2026-11-07T15:42:31.903Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：36.7 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2020-04-16T17:31:52.159Z
- 最新版本发布：2020-05-13T08:53:55.553Z
- 近 30 天下载量：42145095（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 0 个）

## 中文简介

dockerignore是一个兼容多克和节点-ignore API的文件过滤库

## 安装

```sh
npm install @balena/dockerignore
```

也可以使用：`pnpm add @balena/dockerignore`、`yarn add @balena/dockerignore`、`bun add @balena/dockerignore`

## README

# 点球

`dockerignore` 是一个完全兼容 Docker 的文件过滤库 [.dockerignore (英语) 文件](https://docs.docker.com/engine/reference/builder/#dockerignore-file),揭露 和流行的API一样 [忽略](https://github.com/kaelzhang/node-ignore) 软件包 `.gitignore` 格式.

`dockerignore` 还有:

-   可与Linux,macOS和Windows相兼容.
-   与 0 外部依赖关系( 生产安装) 收缩 .
-   纯 Javascript 移植多克戈兰g 执行 `.dockerignore` 格式.
-   测试过几百个测试案例 包括比较实际行为 联 合 国 `docker build` 在 Windows 和 Linux 上.
-   在生产环境中依靠 [巴莱纳克利](https://www.balena.io/docs/reference/balena-cli/), (中文(简体) ), [现在 - cli](https://github.com/zeit/now-cli/) 以及围绕多克建造的其他重要项目.

### 何等为相 `ignore`? 吗?

这个 `.dockerignore` spec 与 `.gitignore`数字 :

-   `*` 内 `.gitignore` 匹配所有东西,而 `.dockerignore` 它只匹配文件中的文件 当前目录( 如 glob) 。 当一个名字被删除时,这种区别很重要 `*` 规则.
-   `abc` 内 `.gitignore` 全部匹配 `abc` 文档和目录,无论嵌入程度如何 内 `.dockerignore` 仅在 `./abc` 而不是在子目录中 `./somedir/abc`。 。 。 .
-   与 `.gitignore`,当父目录被忽略时,子目录不能被重新添加(使用 `!`自此以来 `git` 只是避免走过树下作为优化。 与 `.dockerignore`,即使父目录被忽略,子目录也可以被重新添加.
-   完整差异列表请查看 [.吉提格诺尔 光谱](https://git-scm.com/docs/gitignore) 编辑 [.dockerignore (英语) 光谱](https://docs.docker.com/engine/reference/builder/#dockerignore-file)。 。 。 .

### 何等为相 `ignore`? 吗?

整个API. `dockerignore` 作为叉子开始 [节点](https://github.com/kaelzhang/node-ignore),甚至重复使用同样的 `index.d.ts` 文件 用于类型脚本定义。 在引擎盖下, `node-ignore`匹配逻辑被重写为紧密 匹配 Docker 的执行( 模式主要围绕 [(原始内容存档于2018-09-21) (英语). dockerignore. go](https://github.com/moby/moby/blob/v19.03.8/builder/dockerignore/dockerignore.go) 财务报告和审定财务报表 [fileutils.go 存档副本](https://github.com/moby/moby/blob/v19.03.8/pkg/fileutils/fileutils.go)) (中文(简体) ).

### 兼容性

`dockerignore` 与Node.js版本8及以上合作,在Linux,macOS和Windows上. 代码由 [宝贝](https://babeljs.io/docs/en/)。 。 。 .

## 安装

```bash
npm install --save @balena/dockerignore
```

## 使用量

```js
const ignore = require('@balena/dockerignore')
const ig = ignore().add(['.abc/*', '!.abc/d/'])
```

还列入了打字类型定义:

```typescript
import ignore from '@balena/dockerignore'
const ig = ignore().add(['.abc/*', '!.abc/d/'])
```

### 过滤给定路径

```js
const paths = [
  '.abc/a.js',    // filtered out
  '.abc/d/e.js'   // included
]

ig.filter(paths)        // ['.abc/d/e.js']
ig.ignores('.abc/a.js') // true
```

### 作为过滤功能

```js
paths.filter(ig.createFilter()); // ['.abc/d/e.js']
```

### 支持窗口路径

```js
ig.filter(['.abc\\a.js', '.abc\\d\\e.js'])
// if the code above runs on windows, the result will be
// ['.abc\\d\\e.js']
```

## 后鞭打 _文选._ 前斜线

`dockerignore` 行为与 Docker CLI ("docker building") 相对反斜(`\`(中文(简体) ) 和前斜线`/`)字符:

| 监督办 | 地点 | 斜线( S)`/`(中文(简体) ) | 后斜线( R)`\`(中文(简体) ) |
| --- | --- | --- | --- |
| Linux, 马可操作系统 | `.dockerignore` | 路径分隔符 | 逃脱字符 |
| Linux, 马可操作系统 | `filter()`, (中文(简体) ), `ignores()` | 路径分隔符 | 文件名的一部分 |
| 窗口 | `.dockerignore` | 路径分隔符 | 路径分隔符 |
| 窗口 | `filter()`, (中文(简体) ), `ignores()` | 路径分隔符 | 路径分隔符 |

这意味着,前向鞭可以用于 `.dockerignore` 跨平台文件 兼容性。 这与Windows的一般工作方式一致:前向鞭打 命令提示(cmd.exe)或 PowerShell和戈兰等图书馆功能 [文件路径 。 干净](https://golang.org/pkg/path/filepath/#Clean) 或节点.js [路径](https://nodejs.org/docs/latest-v10.x/api/path.html#path_path_normalize_path)。 。 。 .

使用回击作为逃生字符(只有Linux 和 macOS )在 `.dockerignore` 规格。 "可容忍"的用法可能是为了躲避少数人物 具有特殊的意义 `.dockerignore` 文档,即 `"*#!\"` (不包括双引号),, 相对于在 [常设经常 表达式](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) 总的来说。 任何其他角色的"逃脱"行为(如. `'\\b'`未定义和主题 对具体执行的解释可能随时改变.

## 绝对路径

引导和后导鞭打(或Windows上的回击)从中去除 `.dockerignore` 模式, 这样 `'/a'`, (中文(简体) ), `'a/'` 财务报告和审定财务报表 `'/a/'` 均相当于 `'a'` 在一个 `.dockerignore` 文件,他们都 在匹配相对路径时锁定“ 最左” 目录 。 例如,图案 `'a'` 与 `'x'` 对于给定的路径 `'x/y/z'`。这是多克在戈兰实施 兼容性。 反之,一个给定的绝对路径将无法匹配一个非模糊的图案. 再来 实例:

```js
  ignore().add('a').ignores('a')    // true
  ignore().add('/a').ignores('a')   // true
  ignore().add('/a/').ignores('a')  // true
  ignore().add('a').ignores('/a')   // false
  ignore().add('/a').ignores('/a')  // false
  ignore().add('/a/').ignores('/a') // false
```

考虑采用斜拉式去除方式,可将上述情况减少到:

```js
  ignore().add('a').ignores('a')  // true
  ignore().add('a').ignores('/a') // false
```

这些例子的'假'结果可能似乎与"docker building"的行为不符,何时 docker 文件的源参数 [异常值](https://docs.docker.com/engine/reference/builder/#add) 或者说 [警务](https://docs.docker.com/engine/reference/builder/#copy) 指令是绝对路径 (从一刀起. 解释是,插头将绝对源路径转换为相对 路径( 相对于“ 构建上下文 ” ) **在模式匹配之前 :** [https://github.com/moby/moby/blob/v19.03.8/pkg/archive/archive.go#L806 (英语)](https://github.com/moby/moby/blob/v19.03.8/pkg/archive/archive.go#L806) [https://github.com/moby/moby/blob/v19.03.8/pkg/archive/archive.go#L825 (英语)](https://github.com/moby/moby/blob/v19.03.8/pkg/archive/archive.go#L825)

...同时 `dockerignore` 镜像模式匹配器本身的执行。 建议是 对于您的应用程序,其操作方式与多克CLI相同:使用相对路径进行模式匹配. 这在不同的环境中一般也更为便携:开发机、CI 管道、服务器或终端用户设备.

## 评论

开始的图案 `'#'` (hash)作为评论被忽略. 散列可以使用前缀 为匹配同样以散列开头的文件名而切换或反切:

```js
ignore().add('#abc').ignores('#abc')   // false
ignore().add('/#abc').ignores('#abc')  // true
ignore().add('\\#abc').ignores('#abc') // true
```

之所以成功,是因为从图例中取消了 [绝对 路径](https://npmcn.com/package/%40balena/dockerignore/#readme-absolute-paths)。 。 。 .

## 排除模式

从模式开始 `'!'` (感叹标记)将匹配排除(例外)定义为 记录 [.dockerignore (英语) 规格](https://docs.docker.com/engine/reference/builder/#dockerignore-file)用于 兼容 Docker 执行, 模式从 `'/!'` 或者说 `'!/'` (但无) `'/!/'`)还将被视为排斥模式,此外,在《公约》中描述的切除 [绝对路径](https://npmcn.com/package/%40balena/dockerignore/#readme-absolute-paths)。反斜线以 `'\\!'` 用于匹配 以感叹标记开头的文件或目录名称, 但这只能在 Linux 上使用 和macOS,不在Windows上。 再说一遍,它只是为了和多克的兼容 执行.

## 选项

匹配默认情况下对大小写不敏感, 跟随 `ignore` API 密码 (单位:千美元)[忽略大小写](https://www.npmjs.com/package/ignore#optionsignorecase-since-400)) (中文(简体) ). 但请注意, Docker 执行对大小写敏感的匹配 . 使用 `ignorecase: false` 选项与 Docker 行为一致:

```js
const ig = ignore({ ignorecase: false }) // for case-sensitive matching
```

## 方法

### 添加( 模式)

### 添加( 标签)

-   **模式** `String|Ignore` 忽略模式字符串,或 `Ignore` 实例
-   **模式** `Array.<pattern>` 忽略图案的组合 .

在当前管理器中添加一条规则或若干条规则.

回返 `this`

`pattern` 可能是一行被忽略的图案 也可能是一串被忽略的图案 也就是说我们可以 `ignore().add()` 忽略文件的内容 :

```js
ignore()
.add(fs.readFileSync(filenameOfGitignore).toString())
.filter(filenames)
```

`pattern` 也可能是一个 `ignore` 那样我们就能轻易继承别人的规则 `Ignore` 举个例子.

### .ignores(路径名)

回返 `Boolean` 是否为 `pathname` 应被忽略.

```js
ig.ignores('.abc/a.js')    // true
```

### .filter(路径)

过滤给定的路径名数组,并返回被过滤的数组.

-   **路径** `Array.<path>` 数组 `pathname`s被过滤.

### 创建Filter ()

创建过滤功能,该功能可以使用 `Array.prototype.filter`。 。 。 .

回返 `function(path)` 过滤功能.

## 捐款

总是欢迎捐款!

1.  把这个寄存器分叉到您自己的 GitHub 账户, 然后复制到您的本地设备 .
2.  安装依赖性 : `npm install`
3.  添加测试大小写( 如果适用) 并确保当前失败
4.  添加代码以通过测试
5.  提出牵引请求(将在CI上进行额外测试,以确保测试案例符合实际) `docker build`(中文(简体) )

## 鸣谢

该项目的初步工作由普拉奈·普拉卡什完成 (单位:千美元)[@ pranaygp (英语)](https://twitter.com/pranaygp)) (中文(简体) ) [兹伊特](https://zeit.co/)张凯儿 (单位:千美元)[@kaelzhang (中文(简体) )](https://github.com/kaelzhang))和 [节点 捐助者](https://github.com/kaelzhang/node-ignore/graphs/contributors)。 。 。 .

保罗·卡斯特罗(签名)[@pdcastro (英语)](https://github.com/pdcastro)) (中文(简体) ) [巴莱纳.io](https://www.balena.io/) 2020年建立了储存库[鼓励 泽特](https://github.com/zeit/dockerignore/pull/16#issuecomment-611790479)并放入一个 在Windows支持、跨平台相容和测试方面做出大量努力,最终发布 1.0.0 (中文(简体) ).

## 常见问题

### @balena/dockerignore 是什么？

dockerignore是一个兼容多克和节点-ignore API的文件过滤库

### 如何安装 @balena/dockerignore？

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

### @balena/dockerignore 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/balena\_\_dockerignore 是否存在。

### @balena/dockerignore 支持 ESM 还是 CommonJS？

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

### @balena/dockerignore 可以商用吗？

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

### @balena/dockerignore 的下载量有多少？

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

### @balena/dockerignore 还在维护吗？

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