qpdf로 PDF 구조 검사 — 오류·경고·종료 코드 확인

이미 qpdf를 선택했고 PDF 내부 구조의 진단 결과를 읽으려는 경우입니다. 실행 파일의 공식 배포 선택은 프로그램 페이지에서 확인하세요. 여기서는 Windows의 기본 설정 PowerShell 5.1 또는 PowerShell 7에서 암호 없는 PDF 한 개에 단독 --check를 실행합니다.

파일 탐색기에서 원본을 보관하고 별도의 작업 폴더에 사본을 만듭니다. 같은 이름의 기존 파일을 덮어쓰지 않도록 새 위치를 선택하세요. 파일 확장자 표시와 실제 파일 이름을 확인합니다. 암호가 필요한 자료는 이 예제 대신 소유자에게 검사 가능한 사본을 요청합니다.

공식 ZIP을 사용했다면 압축을 푼 패키지의 구성 파일을 함께 유지하고 bin 폴더의 qpdf.exe를 찾습니다. 다음 경로는 예시입니다. 자기 qpdf.exe와 사본의 실제 전체 경로로 두 값을 모두 바꾸며, exe 경로의 작은따옴표를 유지합니다.

$qpdfCheckExe = 'C:\Tools\qpdf\bin\qpdf.exe'
$qpdfCheckCopy = 'C:\PDF-check\sample-copy.pdf'

& $qpdfCheckExe --check $qpdfCheckCopy
$qpdfCheckExit = $LASTEXITCODE
$qpdfCheckExit

호출 연산자 & 뒤에 실행 파일 변수를 두고 사본 경로를 하나의 인자로 넘깁니다. qpdf 실행 직후 종료 코드를 저장해야 다른 외부 프로그램 실행으로 값이 바뀌는 일을 피할 수 있습니다. 출력의 마지막 숫자는 저장한 코드이며 그 위의 진단 메시지도 함께 읽습니다.

이 명령에는 출력 PDF 경로나 입력 덮어쓰기 옵션이 없습니다. 검사 중 xref 재구성을 시도했다는 메시지가 나와도 고친 PDF를 저장했다는 뜻이 아닙니다. 다른 변환 옵션을 함께 넣거나 경고를 숨기는 명령에는 아래 해석을 그대로 적용하지 않습니다.

0은 문법·스트림 인코딩에서 발견한 문제가 없다는 범위로 읽습니다. PDF 표준 준수·화면 렌더링·글자 추출·접근성·모든 폼의 정상 동작을 보증하는 값은 아닙니다. WARNING이라는 문자열이 있어도 뒤에 오류가 있으면 2일 수 있습니다.

이 표는 --check 단독 실행의 기본 코드입니다. --is-encrypted나 --requires-password 등 다른 검사 옵션은 다른 종료 코드 규칙을 사용합니다. 경고를 종료 코드 0으로 바꾸는 옵션을 넣은 결과와도 구별하세요.

코드 2라면 원본을 그대로 두고 파일을 다시 받거나 생성자에게 정상 사본을 요청할 수 있습니다. 경고가 있거나 화면이 이상한 경우에도 생성 프로그램·전송·저장 경로를 대조하세요. 이 검사를 반복하는 것만으로 손상된 내용이 복원되지는 않습니다.

사용 중인 PDF 뷰어에서 검사한 사본의 페이지 수·그림·글자와 필요한 폼을 확인합니다. 뷰어를 새로 선택해야 한다면 SumatraPDF의 열람 범위를 비교하세요. 구조 진단과 눈으로 보는 내용 검수는 서로 다른 확인입니다.

새 PDF 출력이 필요하거나 다른 페이지 작업을 하려면 qpdf 처리 범위와 공식 옵션으로 돌아가 목적을 다시 확인하세요. 이 가이드는 검사 결과 읽기까지 담당합니다.