圖片壓縮自動化

圖片壓縮自動化 是做什麼的？

總覽

使用 sharp 在數秒內批次調整大小並壓縮產品圖片，輸出為網頁就緒的 .jpg、.webp 或 .avif 檔案，同時保留原始檔案名稱，將透明 PNG 強制加上白色背景，並嚴格維持長寬比（800px 單一高度自動縮放或 WxH 精確檢查）。

核心原則： 絕不假設使用者有特定工作磁碟機（如 F:\），絕不在未經確認的情況下靜默回退到 800x800 或 jpg，也絕不裁剪或扭曲圖片。

快速參考

情境	動作
首次執行（缺少 node_modules/）	執行 npm install（需要 Node.js >= 20.0.0）
缺少 .imagerc.json 且未指定 --dir	詢問使用者其工作資料夾後再執行
未指定目標尺寸/高度或輸出格式	詢問使用者尺寸（800px 高度或 WxH）及格式（jpg、webp 或 avif）後再執行
使用者僅提供高度（例如 800px in webp）	傳入 --size 800px --format webp（自動依每張圖片計算等比例寬度）
使用者提供工作資料夾 + WxH + 格式	執行 node bin/cli.js --dir "<資料夾>" --size "<WxH>" --format <jpg|webp|avif>
使用者有獨立的原始與匯出資料夾	執行 node bin/cli.js --input "<輸入>" --output "<輸出>" --size "<px|WxH>" --format <格式>
精確 WxH 長寬比不匹配	不要裁剪或拉伸；從輸出中報告建議的匹配尺寸（若適當，可建議使用 800px 高度模式）
透明 PNG 背景	自動強制加上 #ffffff 背景（可透過 --bg "#hex" 變更）

逐步代理工作流程

每當使用者要求您使用此儲存庫壓縮或調整圖片大小時，請依序遵循以下步驟：

1. 檢查設定與依賴項

1. 確認 node_modules/sharp 存在。若是全新複製的專案，請執行 npm install。
2. 檢查儲存庫根目錄是否存在 .imagerc.json（除非使用者在提示中已指定資料夾）。
   • 如果 既沒有 .imagerc.json 也沒有使用者指定資料夾，請 先詢問使用者： “您希望使用哪個資料夾作為您的 input 和 output 圖片資料夾？（例如 ./ 代表專案資料夾、~/Desktop/store-images 或 D:\Images。）”
   • 絕不假設使用 F:\Image Compress Automation 或猜測 ~/Desktop。

2. 檢查 input/ 並確認尺寸與格式

1. 確保 <資料夾>/input 和 <資料夾>/output 存在（或傳入 --dir "<資料夾>" 讓 CLI 自動建立）。
2. 檢查輸入資料夾中有多少支援的圖片（.png、.jpg、.jpeg、.webp、.avif）。如果數量為 0，請告知使用者確切的 <資料夾>/input 路徑，請他們將圖片放入該處，然後停止。
3. 如果使用者 尚未 在本次請求中明確指定目標高度/尺寸或輸出格式，請 在執行前詢問 —— 即使非 TTY/無旗標的回退預設為 800x800 和 jpg 也是如此。

3. 以非互動模式執行並報告結果

使用明確的旗標執行 CLI（避免在非 TTY 工具 shell 中使用裸 node bin/cli.js，以免依賴於靜默預設值）：

node bin/cli.js --dir "<工作資料夾>" --size "<HEIGHTpx 或 WIDTHxHEIGHT>" --format "<jpg|webp|avif>"

使用者要求時可用的選擇性旗標：

• --format <jpg|webp|avif>（預設 jpg；webp 約小 25–35%，avif 約小 30–50%）
• --quality <1-100>（JPG mozjpeg 預設 85 / WebP effort: 6 預設值，AVIF effort: 4 預設值 65）
• --bg "<#hex>"（透明 PNG 強制背景預設為 #ffffff）
• --strict（若有任何檔案被跳過或失敗，則返回結束代碼 1）

如果使用者希望為互動式終端執行（npm start）記住此工作資料夾，您可以提及或儲存 .imagerc.json（已被 .gitignore 忽略），或讓使用者執行 npm run setup。

4. 驗證並總結輸出

直接從命令輸出報告：

• 總轉換/跳過/失敗數量及節省空間（MB 和 %）。
• 確切的輸出資料夾路徑（<工作資料夾>/output）。
• 對於任何因 aspect-ratio-mismatch 而跳過的檔案，請顯示 CLI 列印的檔案原始尺寸/比例及建議的等比例尺寸。

常見錯誤與警示

想法 / 錯誤	失敗原因及正確做法
“我直接執行 node bin/cli.js，不加 --size 或 --format”	非 TTY 回退會靜默選擇 800x800 和 jpg。務必先與使用者確認資料夾、尺寸/高度（800px 或 WxH）及格式（jpg/webp/avif），然後傳入 --dir、--size 和 --format。
“使用者想要 800×800，但照片是 1:2 比例——我傳入 fit: cover 或寫一個自訂裁剪腳本”	違反核心規則：絕不靜默裁剪或拉伸。讓 CLI 拒絕不匹配並給出等比例尺寸。
“我會提交 .imagerc.json 或測試 PNG 到 input/”	.imagerc.json、input/* 和 output/*（除了 .gitkeep）已被 .gitignore 忽略，以保護使用者隱私。請保持它們不受追蹤。
“我傳入 --input 但不加 --output”	沒有 --output 或 --dir，輸出會回退到 <cwd>/output。務必傳入 --dir（標準流程）或同時傳入 --input 和 --output。