18강. 문제 해결 흐름: 로그·오류 메시지·재현 절차로 원인 좁히기

?1. 이번 강의에서 해결할 문제

“안 돼요”라는 상태에서 도구를 여러 번 재설치해 원인이 더 복잡해집니다. 같은 오류를 다시 만들 수 있는 최소 절차와 환경 증거를 남깁니다.

✓2. 학습 목표

✓이 강의를 마치면

• 재현, 관찰, 가설, 한 변경, 재검증 순서를 적용합니다.
• 첫 원인 오류와 뒤따른 오류를 구분합니다.
• 명령 출력과 오류를 로그 파일로 안전하게 보존합니다.

◇3. 핵심 개념

문제 해결 기록에는 다음이 있어야 합니다.

1. 기대 결과와 실제 결과
2. 시작 위치와 정확한 명령
3. 도구 버전과 실행 경로
4. 첫 오류 메시지와 재현 단계
5. 바꾼 항목 하나와 재검증 결과

비밀번호, 토큰, 사용자 개인정보와 전체 환경 변수는 로그에 포함하지 않습니다.

✎4. 단계별 실습

PowerShell · 실행 위치: 문제가 발생하는 프로젝트 루트

$logPath = '.\environment-diagnostic.log'

"Time: $(Get-Date -Format o)" | Set-Content $logPath
"Location: $(Get-Location)" | Add-Content $logPath
Get-Command node -All -ErrorAction SilentlyContinue |
    Select-Object Name, Source, Version |
    Out-String | Add-Content $logPath
node --version 2>&1 | Tee-Object -FilePath $logPath -Append
Get-Content $logPath

예상 결과: 시간, 현재 위치, Node 후보와 버전 출력이 로컬 로그에 저장됩니다. Node가 없다면 해당 오류도 기록됩니다. 관리자 권한은 필요하지 않습니다.

문제 기록 · 파일 경로: Docs/environment-issue-template.md

environment-issue-template.md

# Environment issue
- Expected:
- Actual:
- Reproduction steps:
- Working directory:
- Command and version:
- First error:
- One hypothesis:
- One change:
- Retest result:

→5. 명령어와 설정이 동작하는 이유

2>&1은 오류 스트림을 일반 출력과 함께 기록하고 Tee-Object는 화면에 보이면서 파일에도 남깁니다. 시간과 현재 위치를 함께 기록하면 나중에 같은 조건을 재현할 수 있습니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 첫 시도에서 PATH, 버전, 권한을 동시에 변경: 한 가설만 바꾸고 같은 명령으로 재검증합니다.
• 마지막 오류만 검색: 로그 위쪽의 첫 사용자 행동 관련 오류부터 읽습니다.
• 전체 env를 공유: 필요한 변수 이름과 가린 값만 사용하고 비밀을 제외합니다.
• 재설치 전 기존 경로 미기록: Get-Command -All과 버전을 먼저 보존합니다.

✎7. 직접 실습

✎직접 실습

잘못된 현재 경로, 없는 명령 또는 포트 충돌 중 하나를 재현하세요. 템플릿의 모든 항목을 채우고 한 가지 수정만 적용해 같은 절차가 성공하는지 확인합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 문제 해결에서 한 번에 한 항목만 바꾸는 이유는 무엇인가요?
2. 로그에 현재 위치와 시간을 남기면 무엇이 좋아지나요?
3. 전체 환경 변수를 공유하면 안 되는 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

개발 환경 오류는 재현 가능한 명령과 경로·버전·첫 오류를 기록해 좁힙니다. 한 가설만 변경하고 같은 조건으로 재검증해야 원인과 해결책을 구분할 수 있습니다.