# @carboneio/image-size 中文文档

规范地址：https://npmcn.com/package/%40carboneio/image-size/

版本：3\.0\.1
npm 元数据更新时间：2026-10-15T09:53:09.276Z
中文译文更新时间：2026-11-09T12:18:16.683Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：449 kB，117 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.x
- 运行依赖：0 个
- 首次发布：2026-09-08T09:04:17.210Z
- 最新版本发布：2026-10-15T09:53:09.078Z
- 近 30 天下载量：2798（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

获取图像文件的维度

## 安装

```sh
npm install @carboneio/image-size
```

也可以使用：`pnpm add @carboneio/image-size`、`yarn add @carboneio/image-size`、`bun add @carboneio/image-size`

## README

# @ 碳化物/图像大小

快速,轻量级的节点JS包可以得到任何图像文件或缓冲的维度.

## 驾驶员: [碳键](https://carbone.io/)

[![Build and test](https://github.com/carboneio/image-size/actions/workflows/build-test.yml/badge.svg?branch=main)](https://github.com/carboneio/image-size/actions/workflows/build-test.yml) [![NPM Version](https://img.shields.io/npm/v/@carboneio/image-size.svg?style=flat-square)](https://www.npmjs.com/package/@carboneio/image-size) [![Downloads](https://img.shields.io/npm/dm/@carboneio/image-size.svg?style=flat-square)](https://www.npmjs.com/package/@carboneio/image-size) [![Code style: Biome](https://img.shields.io/badge/code_style-biome-60a5fa.svg?style=flat-square)](https://biomejs.dev/) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg?style=flat-square)](https://github.com/carboneio/image-size)

经过对我们的属地进行彻底的安全审计后,我们决定将这个项目叉开(E[gitHub 上的图像大小](https://github.com/image-size/image-size) 财务报告和审定财务报表 [在 Codeberg 上的图像大小](https://codeberg.org/image-size/image-size)解决若干弱点,并在此过程中优化图书馆。 有关变动的详细清单,请参见 [完整更改日志](https://npmcn.com/package/%40carboneio/image-size/CHANGELOG.md)。 。 。 .

我们首先要确保测试套房的密码覆盖率达到100%,然后才做出任何修改。 我们还比较了我们的结果和 [业绩](https://npmcn.com/package/%40carboneio/image-size/#readme-performance) 测试从 [锐口](https://github.com/lovell/sharp),一个被广泛使用,更通用的图书馆.

[![Speedup over image-size 2.0.2, per format, on a logarithmic scale](https://npmcn.com/package/%40carboneio/image-size/assets/performance.svg)](https://npmcn.com/package/%40carboneio/image-size/CHANGELOG.md)

我们热烈地感谢这个图书馆的原始开发者所做的出色工作。 我们之所以维持这一分叉,只是因为我们需要执行一些紧急的纠正和改进措施;一旦原始项目纳入这些改正措施,我们将非常高兴地去掉这一分叉并返回主要存放处.

## 关键特性

-   零依赖关系
-   支持所有主要图像格式
-   处理文件和缓冲器
-   最小内存脚印 - 只读图像头
-   无害环境管理和共同JS支助
-   包含类型脚本
-   通过GitHub Actions CI在节点18、20、22、24和26试验

## 支持的格式

-   银行
-   工会
-   数据交换系统
-   全球投资框架
-   赫克(希弗,阿维克,阿维夫)
-   国际天主教儿童理事会
-   哈里发国
-   J2C 战车
-   JPEG-2000(联合P2)
-   JPEG 组合
-   JPEG-XL 常规
-   KTX(1和2)
-   巴布亚新几内亚
-   PNM( PAM, PBM, PFM, PGM, PPM) :
-   私营部门司
-   特别工作组
-   东京
-   TIFF 时长
-   网络P

## 安装

```shell
npm install @carboneio/image-size
# or
yarn add @carboneio/image-size
# or
pnpm add @carboneio/image-size
```

## 使用量

### 在缓冲/ Uint8 箭头中通过

最适合流,网络请求,或者当您已有内存中的图像数据时.

```javascript
import { imageSize } from '@carboneio/image-size'
// or
const { imageSize } = require('@carboneio/image-size')

const dimensions = imageSize(buffer)
console.log(dimensions.width, dimensions.height)
```

### 从文件中读取

最适合本地文件 。 返回一个承诺.

```javascript
import { imageSizeFromFile } from '@carboneio/image-size/fromFile'
// or
const { imageSizeFromFile } = require('@carboneio/image-size/fromFile')

const dimensions = await imageSizeFromFile('photos/image.jpg')
console.log(dimensions.width, dimensions.height)
```

注意: 从文件读取的默认货币限额为 **100个** 要改变这个限制,你可以打电话 `setConcurrency` 像这样的函数 :

```javascript
import { setConcurrency } from '@carboneio/image-size/fromFile'
// or
const { setConcurrency } = require('@carboneio/image-size/fromFile')
setConcurrency(123456)
```

### 从文件同步读取( 不推荐) QQ

此库的 v1. x 有同步 API, 内部使用同步文件读取 .

之所以不推荐,是因为这样会阻断节点.js主线程,从而降低性能,并阻止这个库同时被使用.

然而,如果您仍然需要同步使用此软件包,您可以将文件同步读取为缓冲器,然后将缓冲器传递到此库.

```javascript
import { readFileSync } from 'node:fs'
import { imageSize } from '@carboneio/image-size'

const buffer = readFileSync('photos/image.jpg')
const dimensions = imageSize(buffer)
console.log(dimensions.width, dimensions.height)
```

### 3\. 指挥线

对快速检查有用.

```shell
npx @carboneio/image-size image1.jpg image2.png
```

### 多尺寸

如果目标文件/缓冲器是HEIF、ICO或CUR文件,则 `width` 财务报告和审定财务报表 `height` 将是一个最大的图像.

额外 `images` 可用数组并返回所有可用图像的尺寸

```javascript
import { imageSizeFromFile } from '@carboneio/image-size/fromFile'
// or
const { imageSizeFromFile } = require('@carboneio/image-size/fromFile')

const { images } = await imageSizeFromFile('images/multi-size.ico')
for (const dimensions of images) {
  console.log(dimensions.width, dimensions.height)
}
```

### 使用一个 URL

```javascript
import url from 'node:url'
import http from 'node:http'
import { imageSize } from '@carboneio/image-size'

const imgUrl = 'http://my-amazing-website.com/image.jpeg'
const options = url.parse(imgUrl)

http.get(options, function (response) {
  const chunks = []
  response
    .on('data', function (chunk) {
      chunks.push(chunk)
    })
    .on('end', function () {
      const buffer = Buffer.concat(chunks)
      console.log(imageSize(buffer))
    })
})
```

### 禁用某些图像类型

```javascript
import { disableTypes } from '@carboneio/image-size'
// or
const { disableTypes } = require('@carboneio/image-size')

disableTypes(['tiff', 'ico'])
```

### JPEG 图像取向

如果在 JPEG EXIF 元数据中存在取向,则会被函数返回. 方向值为 [1至8之间的数字](https://exiftool.org/TagNames/EXIF.html#:~:text=0x0112,8%20=%20Rotate%20270%20CW) 代表一种取向.

```javascript
import { imageSizeFromFile } from '@carboneio/image-size/fromFile'
// or
const { imageSizeFromFile } = require('@carboneio/image-size/fromFile')

const { width, height, orientation } = await imageSizeFromFile('images/photo.jpeg')
console.log(width, height, orientation)
```

# 业绩

`image-size` 读取页眉; [锐口](https://github.com/lovell/sharp) 解码 一个图像。 这使得他们很难在除了这个问题以外的任何事情上进行比较: _学习图像的维度需要多长时间?_ 他们给的一样 回答:跨越锐利自己的501个测试装置,两个库都同意 496,两者都识字.

以尖口0.35.4 / libvips 8.18.6为单位测量,在节点24上为macOS arm64.

**从已经存在记忆中的缓冲器中**,自行分析成本:

| 格式 | 固定线 | 锐口 | 图像大小 | 因素 |
| --- | --- | --: | --: | --: |
| JPEG 组合 | 810 kB, 2725x2225 (英语) | 101微克 | 0.48 微克 | 209辆 |
| 巴布亚新几内亚 | 6.8 MB, 2725x2225 | 76 μs (单位:千兆克) | 0.34 微克 | 226x (英语) |
| 网络P | 173克B, 1024x772 | 206 微秒(206微秒) | 0.52 μs (单位:千兆克) | 400个 |
| 全球投资框架 | 279 kB, 800x533 | 85 μs (单位:千米) | 0.20 微克 | 429辆 |
| TIFF 时长 | 249克B, 246x345 | 122 微克 | 0.63微克 | 195辆 |
| AVIF 亚军 | 279 kB, 2048x858 (英语) | 102微克 | 1.39 μs (单位:千兆克) | 74个 |
| 特别工作组 | 32千贝, 480x360 | 263 微秒(平方厘米) | 2.10微克 | 125辆 |

**从文件路径**,一个应用程序的实际支付,I/O包括:

| 格式 | 大小 | 锐口 | 图像大小 | 因素 |
| --- | --- | --: | --: | --: |
| JPEG 组合 | 810千贝 | 230 微秒( 230 微秒) | 102微克 | 2.3x 双管 |
| 巴布亚新几内亚 | 6.8 甲基溴 | 124微克 | 99 微秒( 99 微秒) | 1\. 3 个 |
| 网络P | 173千贝 | 294微克 | 64 μs (64微秒) | 4.6个 |
| 全球投资框架 | 279千贝 | 191 μs (单位:千米) | 73 微秒( 73 微秒) | 2.6x 单曲 |
| TIFF 时长 | 249克贝 | 285 μs (单位:千米) | 69 微克 | 4.1x (中文(简体) ) |
| AVIF 亚军 | 279千贝 | 342 微克 | 75微克 | 4.6个 |
| 特别工作组 | 32千贝 | 444 μs (单位:千兆克) | 48 μs (单位:千兆克) | 9.2x (中文(简体) ) |

第二张桌子是计划好的 阅读文件 主导成本, 因此缓冲器上的两个数量级缩小到1.3x到 9.2x之间 一旦I/O被计算在内. `image-size` 也没有本地二进制可安装, 也没有 启动成本,其中尖锐支付约50ms 在它的首次呼叫.

libvips 的缓存为这些数字禁用, 因为基准重读 同样的固定在循环中, 否则会测量纪念而不是 工作时 文件在两侧的OS页面缓存中是温暖的. 运行 `npm run bench` 所有30个格式的吞吐量.

# 限制

1.  **部分文件读取**
    
    -   只读图像头, 不读完整文件
    -   一些被破坏的图像可能还会报告维度
2.  **SVG 限制**
    
    -   只支持像素尺寸和视图框
    -   不支持的百分比值
3.  **文件访问**
    
    -   从文件读取的默认货币限额为 100
    -   可用 `setConcurrency()`
4.  **缓冲所需经费**
    
    -   一些格式( 如 TIFF) 需要缓冲中的完整页眉
    -   流出部分缓冲可能不会对所有格式有效

## 发展

```bash
npm ci          # install dependencies from package-lock.json
npm test        # unit tests, with a 100% coverage threshold
npm run bench   # detection throughput, per format, on small and large files
```

`npm run bench` 接受 `--filter=<substring>` 确定单一格式的基准, 譬如说. `npm run bench -- --filter=webp`。 。 。 .

## 许可证

麻省理工学院

## 贷项

不是直接的港口,而是试图有类似的东西 [dabble 的图像化](https://github.com/dabble/imagesize/blob/master/lib/image_size.rb) 作为节点模块.

## [贡献者](https://npmcn.com/package/%40carboneio/image-size/Contributors.md)

## 常见问题

### @carboneio/image-size 是什么？

获取图像文件的维度

### 如何安装 @carboneio/image-size？

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

### @carboneio/image-size 支持 TypeScript 吗？

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

### @carboneio/image-size 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @carboneio/image-size 需要什么版本的 Node\.js？

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

### @carboneio/image-size 可以商用吗？

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

### @carboneio/image-size 的下载量有多少？

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

### @carboneio/image-size 还在维护吗？

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