이미지 압축 자동화은(는) 무엇을 하나요?

개요

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 "<folder>" --size "<WxH>" --format <jpg\|webp\|avif>` 실행
사용자가 별도의 raw 및 export 폴더 사용	`node bin/cli.js --input "<in>" --output "<out>" --size "<px\|WxH>" --format <fmt>` 실행
정확한 `WxH` 종횡비 불일치	잘라내기/늘리기 금지; 출력에서 제안된 일치 크기 보고 (또는 적절한 경우 `800px` 높이 모드 제안)
투명 PNG 배경	`#ffffff`로 자동 평탄화 (`--bg "#hex"`로 변경 가능)

단계별 에이전트 워크플로우

사용자가 이 저장소를 사용하여 이미지 압축 또는 크기 조정을 요청할 때마다 다음 단계를 순서대로 따르세요.

1. 설정 및 종속성 확인

node_modules/sharp가 존재하는지 확인합니다. 새로 클론한 경우 npm install을 실행합니다.
저장소 루트에 .imagerc.json이 있는지 확인합니다(사용자가 이미 프롬프트에서 폴더를 지정하지 않은 경우).
- .imagerc.json이 없고 사용자가 폴더를 지정하지 않은 경우, 먼저 사용자에게 물어보세요: "input 및 output 이미지 폴더로 사용할 폴더를 알려주세요. (예: ./(이 프로젝트 폴더), ~/Desktop/store-images, D:\Images 등)"
- F:\Image Compress Automation 또는 ~/Desktop을 절대 가정하지 마세요.

2. `input/` 검사 및 크기 + 형식 확인

<folder>/input 및 <folder>/output이 존재하는지 확인합니다(또는 --dir "<folder>"를 전달하여 CLI가 생성하도록 합니다).
input 폴더에 지원되는 이미지(.png, .jpg, .jpeg, .webp, .avif)가 몇 개 있는지 확인합니다. 0개인 경우, 사용자에게 이미지를 넣을 정확한 <folder>/input 경로를 알려주고 중단합니다.
사용자가 현재 요청에서 대상 높이/치수 또는 출력 형식을 명시적으로 말하지 않은 경우, 실행 전에 물어보세요 — 비록 non-TTY/플래그 없는 대체가 기본적으로 800x800 및 jpg를 사용하더라도 그렇습니다.

3. 비대화형으로 실행 및 결과 보고

플래그를 명시적으로 사용하여 CLI를 실행합니다(묵시적 기본값에 의존하지 않도록 bare node bin/cli.js는 사용하지 마십시오):

node bin/cli.js --dir "<working-folder>" --size "<HEIGHTpx or WIDTHxHEIGHT>" --format "<jpg|webp|avif>"

사용자가 요청한 경우 선택적 플래그:

--format <jpg|webp|avif> (기본값 jpg; webp는 약 25–35% 작음, avif는 약 30–50% 작음)
--quality <1-100> (JPG mozjpeg / WebP effort: 6의 경우 기본값 85, AVIF effort: 4의 경우 기본값 65)
--bg "<#hex>" (투명 PNG 평탄화를 위한 기본값 #ffffff)
--strict (파일이 건너뛰거나 실패하면 종료 코드 1 반환)

사용자가 대화형 터미널 실행(npm start)을 위해 이 작업 폴더를 기억하길 원하는 경우, .imagerc.json(gitignore에 포함됨)을 언급하거나 저장하거나 npm run setup을 실행하도록 할 수 있습니다.

4. 출력 확인 및 요약

명령 출력에서 직접 보고:

총 변환 / 건너뛰기 / 실패 개수 및 절약된 공간(MB 및 %).
정확한 출력 폴더 경로(<working-folder>/output).
aspect-ratio-mismatch로 건너뛴 경우, 파일의 원본 치수/비율과 CLI가 출력한 제안된 비례 치수를 표시합니다.

일반적인 실수 및 위험 신호

생각 / 실수	실패 이유 및 대처 방법
"`--size`나 `--format` 없이 `node bin/cli.js`만 실행하면 되지"	Non-TTY 대체가 조용히 `800x800`과 `jpg`를 선택합니다. 항상 먼저 사용자와 폴더, 크기/높이(`800px` 또는 `WxH`), 형식(`jpg`/`webp`/`avif`)을 확인하고 `--dir`, `--size`, `--format`을 전달하세요.
"사용자가 1:2 비율 사진을 800×800으로 원해 — `fit: cover`를 전달하거나 커스텀 크롭 스크립트를 작성하지"	핵심 규칙 위반: 절대 이미지를 자르거나 늘리지 마세요. CLI가 불일치를 거부하고 비례 치수를 제공하도록 하세요.
"`.imagerc.json`이나 `input/`의 테스트 PNG를 커밋할게"	`.imagerc.json`, `input/`, `output/`(`.gitkeep` 제외)는 사용자 개인정보 보호를 위해 gitignore됩니다. 추적하지 마세요.
"`--output` 없이 `--input`만 전달하면 되지"	`--output` 또는 `--dir`이 없으면 출력이 `<cwd>/output`으로 대체됩니다. 항상 `--dir`(표준 흐름) 또는 `--input`과 `--output`을 모두 전달하세요.

이미지 압축 자동화