终端图像显示指南：terminal-image 使用全解析

2026-01-25 04:31:24作者：俞予舒Fleming

终端应用在现代软件开发中扮演着重要角色，提升终端体验不仅能增加工作效率，还能带来不一样的编程乐趣。terminal-image 是一个简单而强大的 Node.js 库，它使得在任何支持颜色的终端中显示图片成为可能。无论是本地图片还是远程资源，通过几行代码即可实现。本文档将指导您从安装到使用的全过程，确保您可以自如地在终端中展示您的作品。

安装指南

要开始使用 terminal-image，首先需要确保您的环境中已安装了 Node.js。之后，执行以下命令来添加此库到您的项目中：

npm install terminal-image

这将会下载并安装 terminal-image 及其依赖。

项目使用说明

一旦安装完成，您就可以在您的项目中引入并使用该库。以下是最基础的使用场景：

// 导入 terminal-image 模块
import terminalImage from 'terminal-image';

// 显示本地图片
(async () => {
    console.log(await terminalImage.file('path/to/your/image.jpg'));
})();

在 iTerm 中，由于其对图片的特殊支持，可以显示全分辨率的图像。对于其他终端，图片将依据终端窗口大小自动缩放。

项目API使用文档

核心函数

terminalImage.buffer(imageBuffer, options?)
terminalImage.file(filePath, options?)
terminalImage.gifBuffer(imageBuffer, options?)
terminalImage.gifFile(filePath, options?)

返回一个包含 ANSI 转义码的 Promise 字符串，用于在终端中渲染静态图像或动画 GIF。

自定义选项

height: 图像高度，可为百分比或终端行数。
width: 图像宽度，可为百分比或终端列数，推荐使用百分比以保持适配性。
preserveAspectRatio: 是否保持原图宽高比，默认为 true。

对于动画 GIF，还有额外的选项如 maximumFrameRate 控制最大帧率，以及自定义每一帧的显示方法和停止播放时的回调。

示例：自定义尺寸与比例控制

调整图片尺寸至终端窗口的一半：

import terminalImage from 'terminal-image';

(async () => {
    console.log(await terminalImage.file('image.jpg', { width: '50%', height: '50%' }));
})();

显示远程图片

如果您想在终端显示网络上的图片，可以通过先下载图片为缓冲区再进行显示：

import terminalImage from 'terminal-image';
import got from 'got'; // 假设您已经安装了 got 来获取 HTTP 资源

(async () => {
    const imageUrl = 'https://example.com/path/to/image.jpg';
    const imageBuffer = await got(imageUrl).buffer(); // 获取图片数据
    console.log(await terminalImage.buffer(imageBuffer)); // 在终端显示
})();