imgtran

imgtran

快速圖片格式轉換 CLI 工具，支援 macOS 和 Windows 11。

✨ 特色

• 🚀 快速批次轉換圖片格式
• 🎯 支援 WebP、AVIF、JPEG、PNG、GIF
• 🎨 互動模式：直覺的選單式界面
• 📦 可選 ZIP 壓縮包輸出
• 🔧 靈活的設定選項
• 💻 完整跨平台支援 (macOS / Windows 11)
• 🖥️ 美觀的終端機輸出
• ⚙️ 支援全域與專案設定檔

📦 安裝

全域安裝（推薦）

npm install -g imgtran

本地專案安裝

npm install --save-dev imgtran

NPX 直接使用（無需安裝）

npx imgtran -i ./images -o ./output

🚀 快速開始

🎨 互動模式（推薦新手）

互動模式提供直覺的選單式界面，讓您輕鬆設定所有選項：

# 啟動互動模式
imgtran --interactive

# 或指定輸入資料夾後啟動互動模式
imgtran --interactive -i ./photos

互動模式會逐步詢問：格式、品質、輸出路徑等選項，並可將設定儲存為預設值。

👉 查看互動模式完整說明

基本使用（指令模式）

# 轉換當前目錄的 images 資料夾到 output
imgtran

# 指定輸入和輸出資料夾
imgtran -i ./src/images -o ./dist/images

# 指定格式和品質
imgtran -i ./images -o ./output -f avif -q 85

# 產生 ZIP 壓縮包
imgtran -i ./images -o ./output --zip

Windows 11 使用範例

# PowerShell
imgtran -i .\images -o .\output --quality 90

# CMD
imgtran -i .\images -o .\output --quality 90

# Git Bash
imgtran -i ./images -o ./output --quality 90

macOS 使用範例

# 基本轉換
imgtran -i ~/Pictures/photos -o ~/Pictures/optimized

# 遞迴處理子資料夾
imgtran -i ./images -o ./output --recursive

# 詳細輸出
imgtran -i ./images -o ./output --verbose

📖 命令選項

選項:
  -i, --input <path>       輸入資料夾路徑 (預設: "./images")
  -o, --output <path>      輸出資料夾路徑 (預設: "./output")
  -q, --quality <number>   轉換品質 1-100 (預設: 90)
  -f, --format <format>    輸出格式: webp, avif, jpeg, jpg, png, gif (預設: "webp")
  --prefix <string>        檔名前綴
  --suffix <string>        檔名後綴
  -z, --zip                產生 ZIP 壓縮包
  -r, --recursive          遞迴處理子資料夾
  --overwrite              覆寫已存在的檔案
  -c, --config <path>      設定檔路徑
  -v, --verbose            詳細輸出
  --interactive            🎨 互動模式：顯示選項選單
  -V, --version            顯示版本
  -h, --help               顯示幫助

⚙️ 設定檔

imgtran 支援三種層級的設定檔，優先順序如下：

• CLI 參數（最高優先）
• 專案設定檔（imgtran.config.js 或 .imgtranrc）
• 全域設定檔（~/.imgtranrc）（最低優先）

全域設定檔（推薦）

在你的家目錄建立 .imgtranrc 檔案，所有專案都會使用這些預設設定：

macOS / Linux:

# 建立全域設定檔
nano ~/.imgtranrc

Windows:

# 建立全域設定檔
notepad C:\Users\你的用戶名\.imgtranrc

設定檔內容（JSON 格式）:

{
  "quality": 90,
  "format": "webp",
  "suffix": "_optimized",
  "verbose": true,
  "zip": false
}

專案設定檔

建立 imgtran.config.js 或 .imgtranrc 在專案根目錄（會覆蓋全域設定）:

JavaScript 設定檔

// imgtran.config.js
export default {
  input: './images',
  output: './output',
  quality: 90,
  format: 'webp',
  prefix: '',
  suffix: '_optimized',
  zip: false,
  recursive: false,
  overwrite: false,
  verbose: true,
}

JSON 設定檔

{
  "input": "./images",
  "output": "./output",
  "quality": 90,
  "format": "webp",
  "zip": true
}

使用設定檔:

# 自動搜尋設定檔
imgtran

# 指定設定檔
imgtran -c ./my-config.js

💡 使用範例

範例 1: 將 PNG 轉換為 WebP

imgtran -i ./png-images -o ./webp-images -f webp -q 90

範例 2: 批次處理並加上後綴

imgtran -i ./images -o ./optimized --suffix "_opt" -f avif

範例 3: 遞迴處理所有子資料夾

imgtran -i ./assets -o ./dist --recursive -v

範例 4: 產生 ZIP 方便分享

imgtran -i ./photos -o ./compressed --zip -f jpeg -q 85

範例 5: 在 package.json 中使用

{
  "scripts": {
    "optimize": "imgtran -i ./public/images -o ./public/optimized",
    "build:images": "imgtran -c imgtran.config.js"
  }
}

🔧 作為 Library 使用

你也可以在 Node.js 專案中將 imgtran 作為 library 使用:

import { convertImage, scanInputFiles } from 'imgtran'

const files = await scanInputFiles('./images')
// 處理圖片...

🌍 跨平台支援

Windows 11

• ✅ 完整支援 PowerShell、CMD、Git Bash
• ✅ 自動處理路徑分隔符差異
• ✅ Sharp 自動下載對應 binary

macOS

• ✅ 完整支援所有終端機
• ✅ 原生效能最佳化

🐛 常見問題

Windows: 找不到 node 或 npm

# 安裝 Node.js
winget install OpenJS.NodeJS

# 重啟 PowerShell

macOS: Permission denied

# 使用 sudo 安裝
sudo npm install -g imgtran

Sharp 安裝失敗

Sharp 會自動下載對應平台的 binary，如果失敗:

# 清除快取重新安裝
npm cache clean --force
npm install -g imgtran

📝 授權

MIT

🤝 貢獻

歡迎提交 Issue 和 Pull Request!