资源描述
progress 是一个轻量、高性能的 JavaScript CLI 进度条框架，专为 Node.js 命令行应用设计。支持多阶段进度、动态速率估算、自定义样式与主题，兼容 Windows/macOS/Linux 终端。适用于构建 npm 包、CLI 工具、自动化脚本及构建系统（如打包、下载、迁移任务），显著提升用户等待体验与交互反馈质量。
详细内容
# progress — 高度可定制的 CLI 进度条框架
## 简介与定位
`progress` 是一个面向现代 Node.js CLI 应用的轻量级进度可视化框架，由 Nathan P. Brown 开发并持续维护。它不依赖 DOM 或浏览器环境，专为终端（TTY）场景优化，提供声明式 API 与细粒度控制能力，帮助开发者在命令行中直观呈现长时间运行任务的执行状态，是 CLI 工具用户体验升级的关键基础设施。
## 核心特性
- ✅ **多模式进度支持**：单阶段线性进度、多步骤分段进度（`step()`）、带子任务嵌套的树状进度（`group()`）
- ✅ **实时动态渲染**：基于 `process.stdout` 的高效刷新机制，自动适配终端宽度，避免闪烁与换行错位
- ✅ **完全可定制外观**：支持自定义前缀/后缀、进度字符（如 `█`, `░`, `→`）、颜色（ANSI 256 色/RGB）、填充比例与空格策略
- ✅ **智能速率与 ETA 计算**：内置 `speed()` 和 `eta()` 方法，自动估算剩余时间与吞吐速率（单位：items/sec 或 bytes/sec）
- ✅ **无障碍友好设计**：默认禁用动画/闪烁，支持 `--no-progress` 全局静默模式，兼容 CI/CD 环境与屏幕阅读器（通过 `aria-label` 类似语义注释）
## 适用场景
- 构建工具中的文件打包/压缩进度（如 esbuild、vite 插件）
- 数据迁移或批量处理 CLI（如数据库同步、日志清洗）
- 文件下载/上传工具（配合 `axios` 或 `node-fetch` 流式响应）
- npm/yarn/pnpm 自研 CLI 的交互增强（如 `create-*` 脚手架）
- CI 构建日志中关键阶段的可视化标记（需结合 `CI=false` 环境变量降级）
## 快速入门
### 安装
```bash
npm install progress
# 或
yarn add progress
```
### 最小示例（单阶段进度）
```js
import { Progress } from 'progress';
const bar = new Progress({
format: '[:bar] :current/:total (:percent%) :etas',
width: 40,
total: 100,
});
for (let i = 0; i <= 100; i++) {
bar.update(i);
await new Promise(r => setTimeout(r, 50)); // 模拟异步工作
}
```
> 输出效果：`[██████████████████████████████████████] 100/100 (100%) 0s`
## 生态与社区
- 主页与文档：[https://progress.nathanpb.dev/](https://progress.nathanpb.dev/)（含完整 API 参考与主题配置指南）
- 源码托管于 GitHub（公开仓库，MIT 协议），Issue 与 PR 响应活跃
- 已被多个知名 CLI 工具间接集成（如部分 `@oclif` 插件生态项目），社区提供 TypeScript 类型定义（`@types/progress`）
- 不提供官方插件市场，但支持通过 `bar.set()` 和事件钩子（`on('update')`, `on('complete')`）灵活扩展行为