← Home

TAB Project Wiki

Windows PowerShell 5.1 CLI 트러블슈팅 패턴 모음

Properties3
descriptionA catalog of recurring Windows PowerShell 5.1 pitfalls encountered while automating Cloudflare/wrangler CLI workflows — encoding, piping, secrets, and path-wildcard bugs that silently corrupt data or break dynamic parameter binding.
tagstab-project, concept, powershell, troubleshooting, windows
aliasesPowerShell 5.1 Gotchas, Windows PowerShell CLI Troubleshooting Catalog

7 min read

Windows PowerShell 5.1 CLI 트러블슈팅 패턴 모음

Key Insight

wrangler(Cloudflare CLI) 자동화를 Windows PowerShell 5.1로 진행하면서 반복적으로 마주친 함정들을 모은 카탈로그다. 공통점: 대부분 에러 메시지 없이 조용히 값이 깨지거나(인코딩류) 동작이 예상과 다르게 흘러간다(경로/파라미터 바인딩류) — 발견하기 어렵고, 알고 있으면 즉시 회피 가능하다.

Overview

turboairbrain.uk 발행(Obsidian 볼트를 Cloudflare Pages로 웹 발행하기)과 Q&A 봇 구축(Cloudflare Pages Function + Claude API로 Wiki 기반 Q&A 봇 만들기) 두 세션에 걸쳐 발견된 PowerShell 5.1 관련 버그 10건을 정리한다. BOM 관련 1건은 이미 전용 페이지(PowerShell CLI 파이프의 BOM 오염 문제)가 있으므로 여기서는 요약만 두고 링크한다.

Details

인코딩 계열

  1. stdin 파이프 BOM 오염: "value" | tool.exe로 문자열을 넘기면 UTF-8 BOM(U+FEFF)이 값 앞에 몰래 붙을 수 있다 — 상세: PowerShell CLI 파이프의 BOM 오염 문제.
  2. .ps1 스크립트 파일 자체의 BOM 없는 UTF-8 → 한글 리터럴 오독: 스크립트에 직접 작성한 한글 문자열이 실행 시 mojibake로 깨진다. 해결: 파일을 BOM 있는 UTF-8로 재저장 — [System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($true)).
  3. 외부 프로세스 stdout 캡처 시 코드페이지 불일치: & npx wrangler kv key get ...로 받은 한글 JSON이 별도로 깨진다(2번과 다른 버그 — 하나만 고치면 나머지 절반은 계속 깨진 채 남는다). 해결: 스크립트 최상단에 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 + $OutputEncoding = [System.Text.Encoding]::UTF8.
  4. PowerShell → 네이티브 프로세스 파이프가 값을 truncate: "apikey" | wrangler pages secret put ...가 재현 불가능하게 값을 1글자로 잘랐다. 같은 시스템의 Bash(Git Bash) 파이프(cat apikey.txt | npx wrangler ...)는 문제없이 동작 — Windows PowerShell 5.1의 파이프-투-네이티브프로세스 경로 전반이 신뢰도가 낮다는 결론.
  5. 인터랙티브 마스킹 프롬프트에 긴 문자열 붙여넣기 불안정: wrangler의 “Enter a secret value: ***” 같은 프롬프트에 붙여넣기가 손실 없이 되지 않는 경우가 있었다.

CLI 동작/옵션 계열

  1. wrangler kv 기본값은 로컬 시뮬레이션: --remote 플래그 없이는 로컬 가짜 저장소에 쓴다 — 실제 배포된 Function은 이걸 못 본다. 모든 KV 명령에 --remote 필수.
  2. wrangler pages secret put에는 --path 옵션이 없다: wrangler kv key put에만 있는 옵션과 혼동하기 쉽다 — 시크릿은 stdin 파이프 또는 인터랙티브 프롬프트로만 입력 가능.
  3. Cloudflare Pages 시크릿은 소급 적용되지 않음: wrangler pages secret put으로 값을 바꿔도 이미 배포된 live Function은 옛 값을 계속 쓴다 — 새 배포를 만들어야 반영된다.
  4. ConvertFrom-Json이 빈 배열 "[]"을 $null로 반환: @($null)은 원소 1개(그 원소가 null)짜리 배열이 되어, foreach가 “빈 리스트인데도” 한 번 돌며 하위 명령이 “Not enough non-option arguments” 에러로 실패한다. 해결: @($json | ConvertFrom-Json) | Where-Object { $null -ne $_ }.

경로/파라미터 바인딩 계열 (2026-08-04 신규 발견)

  1. 경로에 와일드카드 문자([ ] { })가 있으면 동적 파라미터 바인딩이 깨짐: Set-Content -Path/Test-Path의 -Encoding은 FileSystem 프로바이더가 제공하는 동적 파라미터로, -Path 값이 와일드카드 패턴으로 해석되면([/] 포함) 경로 리졸브 방식이 달라지면서 -Encoding 자체를 찾지 못하는 “A parameter cannot be found that matches parameter name ‘Encoding’” 에러가 난다. 파일명 슬러그에 대괄호가 섞여 들어간 경우(예: 사용자 입력을 그대로 슬러그화)에 처음 발현됐다 — 슬러그 새니타이즈 정규식에 [ ] { } \`` 를 포함해도 놓치는 케이스에 대비해, **-Path대신 항상-LiteralPath`를 쓰는 것이 근본 해결**이다.

Sources

Open Questions

Open Question

이 목록의 버그들이 PowerShell 7(pwsh, cross-platform)에서도 재현되는지 검증되지 않았다 — 전부 Windows PowerShell 5.1(powershell.exe) 기준 관찰이다.

Bias Check

Counter-argument: 모두 단일 사용자·단일 머신(Windows 11)에서의 관찰이다 — 다른 Windows 빌드, 다른 로캘(non-ko-KR) 설정에서 동일하게 재현되는지는 확인하지 못했다. Data gap: 각 버그의 근본 원인(예: 10이 정확히 어느 PowerShell 내부 메커니즘 때문인지)까지 깊이 파고들지는 않았다 — 실용적 회피책 확인에 그쳤다.

그래프 뷰

백링크