Windows에서 쓰는데 문서대로 안 된다
샌드박스 미지원, 경로 변환, CRLF 세 가지가 대부분의 원인이다.
공식 문서는 macOS/Linux를 전제로 쓰인 부분이 많다. Windows에서 갈리는 지점만 모았다.
1. 샌드박스는 네이티브 Windows에서 안 된다
sandbox.enabled 를 켜도 동작하지 않는다. macOS는 Seatbelt, Linux/WSL2는 bubblewrap을 쓰는데 Windows용 구현이 없다. 격리가 필요하면 WSL2 안에서 실행할 것.
2. Git Bash에서 Windows 경로를 그대로 넘기지 않는다
file:///tmp/... 같은 POSIX 경로를 Chrome이나 Windows 네이티브 프로그램에 넘기면 조용히 실패하지 않는다 — 에러 페이지를 정상 산출물로 만들어낸다. cygpath -m 으로 변환해서 넘길 것.
P=$(cygpath -m "$PWD")
chrome.exe --headless --print-to-pdf="$P/out.pdf" "file:///$P/in.html"
3. 줄바꿈을 고정한다
.gitattributes 에 * text=auto eol=lf 를 넣지 않으면 CRLF가 섞여 diff가 통째로 바뀐 것처럼 보인다. 데이터 파일이 많은 리포에서 특히 심하다.
4. 글롭 패턴에 역슬래시를 섞지 않는다
경로를 코드로 조립할 때 역슬래시가 들어가면 fast-glob/picomatch가 에러 없이 0건을 반환한다. path.posix 를 쓰거나 .split(path.sep).join("/") 로 정규화할 것.
5. 한글 폰트를 고정한다
로컬 Windows에서는 Malgun Gothic이 잡히지만 CI(Ubuntu)에는 CJK 폰트가 없다. fonts-noto-cjk 를 설치하지 않으면 한글이 전부 □로 나오는데, PDF는 정상 생성되고 페이지 수·크기 검사도 통과하므로 자동 검사로는 절대 안 잡힌다.
주의
"로컬에선 되는데 CI에서 다르다"의 원인 대부분이 이 목록에 있다. 로컬에서만 통과하는 검사는 검사가 아니다 — 산출물을 만드는 환경을 옮길 계획이면 폰트와 경로부터 고정할 것.
데이터 src/_data/tasks/windows-gotchas.yaml
틀린 게 있으면 이 파일을 고치면 사이트·검색·치트시트가 같이 바뀐다.