placeholder-image-cli (pd-img)

一个轻量级、功能丰富的命令行占位图片生成工具。当你在开发中需要一个占位图片时，可以使用这个工具一键生成。

支持生成 PNG、JPG、SVG、WebP 格式，支持自定义尺寸、背景色、文本内容、字体样式及圆角等。

• 中文文档：从这里开始往下看即可
• English docs: see English

特性

• 🚀 一键生成：通过简单的命令快速生成测试图片。
• 🎨 高度自定义：支持自定义宽高、背景色、文本内容、字体大小/颜色/字体族。
• 🔲 圆角支持：支持生成带圆角的透明背景图片。
• 🖼️ 多格式支持：支持 PNG, JPEG, WebP, SVG 多种输出格式。
• ⚡ 自动推断：根据输出文件名后缀自动推断生成格式。
• 📂 自动创建目录：如果输出路径的目录不存在，会自动创建。

安装

需要 Node.js >= 14。

# 全局安装
npm install -g placeholder-image-cli

# 或者使用 npx 临时运行（无需全局安装）
npx --yes --package placeholder-image-cli pd-img [options]

使用方法

安装后，你可以使用 pd-img 或 placeholder-image 命令。

pd-img [options]

选项说明

| 参数 (简写) | 描述 | 默认值 | | :--- | :--- | :--- | | --width, -w | 图片宽度 | 300 | | --height, -h | 图片高度 | 200 | | --sizes | 批量尺寸列表，例如 300-200,400-300（也兼容 300x200） | - | | --count, -n | 批量生成数量（可与 --sizes 叠加） | 1 | | --size, -z | 目标文件体积，例如 120000 / 120kb / 1.5mb（做大可通过填充实现；无法精确时输出最接近） | - | | --bg, -b | 背景颜色 (支持 Hex, RGB, RGBA) | #CCCCCC | | --text, -t | 文本内容 | <width>x<height> | | --fontSize, -s | 文本字号 (px) | min(w,h)*0.18 | | --color, -c | 文本颜色 | #333333 | | --fontFamily | 字体族 | Arial, Helvetica... | | --radius, -r | 圆角大小 (px) | 0 | | --format, -f | 输出格式 (png, jpg, svg, webp) | png | | --out, -o | 输出文件路径 | ./placeholder-<ts>.png | | --lang, -l | 帮助信息语言（zh/en） | zh | | --help | 显示帮助信息 | - |

注意：

1. 颜色值建议加上引号，例如 "#ff0000"，以避免终端解析错误。
2. 带有空格的文本内容必须加上引号，例如 "Hello World"。
3. --format 可省略：当 --out 带有 .png/.jpg/.jpeg/.webp/.svg 后缀时，会自动推断格式。
4. 批量尺寸 --sizes 推荐使用 - 分隔（例如 300-200），同时也兼容 x（例如 300x200）。

国际化（i18n）

当前仅对 --help 帮助文案做了中英文切换。

# 英文帮助
pd-img --lang en --help

# 中文帮助
pd-img --lang zh --help

也支持通过环境变量设置默认语言（命令行参数优先级更高）：

# Windows PowerShell
$env:PD_IMG_LANG="en"
pd-img --help

# macOS / Linux
export PD_IMG_LANG=en
pd-img --help

可用环境变量：

• PD_IMG_LANG
• PLACEHOLDER_IMAGE_LANG

示例

1. 最简单的用法 生成一个默认的 300x200 PNG 图片，文件名包含时间戳。

pd-img

2. 自定义尺寸和颜色 生成 400x300，黄色背景，深色文字。

pd-img -w 400 -h 300 -b "#ffcc00" -c "#333"

3. 生成圆角透明图片 生成 200x200，红色背景，50px 圆角，输出为 avatar.png。

pd-img -w 200 -h 200 -b "#ff0000" -r 50 -o avatar.png

4. 生成 WebP 格式 工具会自动根据后缀推断格式。

pd-img -w 500 -h 300 -t "WebP Image" -o banner.webp

5. 生成 SVG (纯矢量) 生成 SVG 文件，无损缩放。

pd-img -w 100 -h 100 -f svg -o icon.svg

6. 批量生成（多尺寸 / 多张）

# 生成 3 个不同尺寸（输出到目录）
pd-img --sizes 300-200,400-300,500-400 -o ./out

# 生成 10 张同尺寸（自动加序号）
pd-img -w 300 -h 200 --count 10 -o ./out

# 多尺寸 + 每个尺寸 3 张
pd-img --sizes 300-200,400-300 --count 3 -o ./out

7. 指定文件体积（尽量接近）

# 尽量生成接近 120kb 的 JPG（无法精确时输出最接近）
pd-img -w 800 -h 600 -f jpg --size 120kb -o ./out

开发与本地运行

# 安装依赖
pnpm install

# 查看帮助（等同于 node bin/placeholder-image.js --help）
pnpm start

# 传递参数给脚本（pnpm 需要加 --）
pnpm start -- --lang en --help

License

MIT

English

A lightweight yet feature-rich CLI tool for generating placeholder images. When you need quick placeholder assets during development, this tool can generate them in one command.

Supports PNG, JPG, SVG, WebP. You can customize size, background color, text content, font style, and corner radius.

Features

• 🚀 One-command generation: quickly generate test images with a simple command.
• 🎨 Highly customizable: width/height, background, text, font size/color/family.
• 🔲 Rounded corners: generate images with rounded corners.
• 🖼️ Multiple formats: PNG, JPEG, WebP, SVG.
• ⚡ Auto inference: infer output format from the output filename extension.
• 📂 Auto create directories: automatically create the output directory if it doesn't exist.

Installation

Requires Node.js >= 14.

# Install globally
npm install -g placeholder-image-cli

# Or run via npx (no global install)
npx --yes --package placeholder-image-cli pd-img [options]

Usage

After installation, you can use pd-img or placeholder-image.

pd-img [options]

Options

| Option (alias) | Description | Default | | :--- | :--- | :--- | | --width, -w | Image width | 300 | | --height, -h | Image height | 200 | | --sizes | Batch sizes, e.g. 300-200,400-300 (also supports 300x200) | - | | --count, -n | Batch count (can be combined with --sizes) | 1 | | --size, -z | Target file size, e.g. 120000 / 120kb / 1.5mb (can be increased via padding; returns the closest result when exact is not possible) | - | | --bg, -b | Background color (Hex/RGB/RGBA) | #CCCCCC | | --text, -t | Text content | <width>x<height> | | --fontSize, -s | Font size (px) | min(w,h)*0.18 | | --color, -c | Text color | #333333 | | --fontFamily | Font family | Arial, Helvetica... | | --radius, -r | Corner radius (px) | 0 | | --format, -f | Output format (png, jpg, svg, webp) | png | | --out, -o | Output file path | ./placeholder-<ts>.png | | --lang, -l | Help language (zh/en) | zh | | --help | Show help | - |

Notes:

1. Quote color values (e.g. "#ff0000") to avoid shell parsing issues.
2. Quote text values if they contain spaces (e.g. "Hello World").
3. --format is optional: if --out ends with .png/.jpg/.jpeg/.webp/.svg, the format is inferred automatically.
4. For --sizes, - is recommended (e.g. 300-200). x is also supported (e.g. 300x200).

i18n

Currently only the --help output supports Chinese/English.

# English help
pd-img --lang en --help

# Chinese help
pd-img --lang zh --help

You can also set the default language via environment variables (CLI args take precedence):

# Windows PowerShell
$env:PD_IMG_LANG="en"
pd-img --help

# macOS / Linux
export PD_IMG_LANG=en
pd-img --help

Supported environment variables:

• PD_IMG_LANG
• PLACEHOLDER_IMAGE_LANG

Examples

1. Minimal Generate a default 300x200 PNG with a timestamp in the filename.

pd-img

2. Custom size & colors

pd-img -w 400 -h 300 -b "#ffcc00" -c "#333"

3. Rounded corners Generate a 200x200 image with 50px radius and save as avatar.png.

pd-img -w 200 -h 200 -b "#ff0000" -r 50 -o avatar.png

4. WebP Format is inferred from the extension.

pd-img -w 500 -h 300 -t "WebP Image" -o banner.webp

5. SVG (vector)

pd-img -w 100 -h 100 -f svg -o icon.svg

6. Batch (multi-size / multi-count)

# 3 different sizes (output to a directory)
pd-img --sizes 300-200,400-300,500-400 -o ./out

# 10 images with the same size (auto indexed)
pd-img -w 300 -h 200 --count 10 -o ./out

# Multi-size + 3 images per size
pd-img --sizes 300-200,400-300 --count 3 -o ./out

7. Target file size (best effort)

# Generate a JPG close to 120kb (returns the closest result when exact is not possible)
pd-img -w 800 -h 600 -f jpg --size 120kb -o ./out

Development (local)

# Install dependencies
pnpm install

# Print help (same as node bin/placeholder-image.js --help)
pnpm start

# Pass arguments to the underlying script (pnpm requires --)
pnpm start -- --lang en --help

License

MIT