디버깅 가이드
이 문서는 Node.js 앱과 스크립트의 디버깅을 도울 것입니다.
인스펙터 활성화
--inspect
스위치로 시작하면 Node.js 프로세스가 디버깅 클라이언트에서 수신을
시작하고 기본 호스트와 포트로 127.0.0.1:9229
를 사용합니다. 각 프로세스는
고유한 UUID도 할당받습니다.
인스펙터 클라이언트는 호스트 주소, 포트, UUID를 알아야 접속할 수 있습니다. 전체
URL은 ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e
같은 형태가
됩니다.
Node.js가 SIGUSR1
신호를 받으면 디버깅 메시지도 수신하기
시작합니다.(SIGUSR1
은 Windows에서는 사용할 수 없습니다.) Node.js 7 이하
버전에서는 레거시 Debugger API가 활성화되고 Node.js 8 이상에서는 Inspector API를
활성화합니다.
보안 관련
디버거가 Node.js 실행 환경에 완전히 액세스하기 때문에 이 포트에 연결할 수 있는 공격자가 노드 프로세스를 대신하여 임의의 코드를 실행할 수 있습니다. 디버거 포트를 공용 및 개인 네트워크에 노출하는 경우 보안에 미치는 영향을 이해하는 것은 중요합니다.
디버그 포트를 공개적으로 노출하는 것은 안전하지 않습니다.
디버거가 퍼블릭 IP 주소 또는 0.0.0.0에 바인딩 될 경우 IP 주소에 접근할 수 있는 어떤 클라이언트든 아무 제약 없이 디버거에 접속할 수 있고 임의의 코드를 실행할 수 있습니다.
기본적으로 node --inspect
는 127.0.0.1에 바인딩 합니다. 디버거에 외부 접속을 허용하려 할 경우 퍼블릭 IP 주소 또는 0.0.0.0 등을 명시적으로 제공해야 합니다. 이렇게 하면 잠재적으로 심각한 보안 위협에 노출될 수 있습니다. 보안 노출을 방지하기 위해 적절한 방화벽과 액세스 제어를 유지하는 것이 좋습니다.
원격 디버거 클라이언트의 접근을 안전하게 허용하는 방법은 '원격 디버깅 활성화 시나리오' 섹션을 참조하십시오.
로컬 애플리케이션은 인스펙터에 완전히 액세스 할 수 있습니다.
인스펙터 포트를 127.0.0.1(기본값)에 바인딩하더라도 시스템에서 로컬로 실행되는 애플리케이션들은 제한 없이 액세스 할 수 있습니다. 이것은 로컬 디버거를 편리하게 부착할 수 있도록 의도적으로 설계되었습니다.
브라우저, 웹소켓, 동일 출처 정책
웹 브라우저에서 열리는 웹사이트는 브라우저 보안 모델에 따라 웹소켓과 HTTP 요청을 할 수 있습니다. 고유한 디버거 세션 ID를 얻으려면 초기 HTTP 연결이 필요합니다. 동일 출처 정책은 이 HTTP 연결을 만들 수 없도록 합니다. DNS 리바인딩 공격에 대한 추가 보안을 위해 Node.js는 연결의 'Host' 헤더가 IP 주소나 localhost
또는 localhost6
을 정확하게 지정하는지 검증합니다.
이러한 보안 정책은 호스트 이름을 지정하여 원격 디버그 서버에 접속할 수 없도록 합니다. IP 주소를 지정하거나 아래에 설명된 것과 같이 ssh 터널을 사용하여 이 제한사항을 해결할 수 있습니다.
인스펙터 클라이언트
Node 인스펙터에 접속할 수 있는 여러 상용 도구와 오픈소스 도구가 있습니다. 아래에 이러한 도구들을 간략하게 정리했습니다.
node-inspect
- Node.js 재단에서 지원하는 CLI 디버거로 Inspector 프로토콜을 사용합니다.
- Node에 포함되어 있고
node inspect myscript.js
로 사용할 수 있습니다. - 최신 버전을 별도로 설치할 수 있고(예시:
npm install -g node-inspect
)node-inspect myscript.js
로 사용할 수 있습니다.
Chrome DevTools 55+
- 방법 1: 크로미움에 기반을 둔 브라우저에서
chrome://inspect
를 엽니다. Configure 버튼을 눌러서 대상 호스트와 포트 목록을 확인합니다. - 방법 2:
/json/list
(상단 참고)의 출력에서devtoolsFrontendUrl
을 복사하거나 --inspect가 알려준 텍스트에서 복사해서 크롬에 붙여넣기를 합니다.
Visual Studio Code 1.10+
- Debug 패널에서 설정 아이콘을 클릭해서
.vscode/launch.json
을 엽니다. 초기 설정으로 "Node.js"를 선택하세요.
Visual Studio 2017
- 메뉴에서 "Debug > Start Debugging"을 선택하거나 F5를 누르세요.
- 상세한 설명
JetBrains WebStorm 2017.1+와 다른 JetBrains IDE
- 새로운 Node.js 디버그 설정을 생성하고 Debug를 누르세요. Node.js 7+에서는
기본적으로
--inspect
를 사용할 것입니다. 비활성화하려면 IDE 레지스트리에서js.debugger.node.use.inspect
의 체크를 해제하세요.
chrome-remote-interface
- 인스펙터 프로토콜 엔드포인트로의 연결을 쉽게 하는 라이브러리입니다.
Gitpod
Debug
뷰에서 Node.js 디버그 설정을 실행하거나F5
키를 누르세요. 자세한 방법은 여기를 참고하세요.
Eclipse IDE와 Eclipse Wild Web Developer 확장 프로그램
- .js 파일에서 "Debug As... > Node program"을 선택하거나,
- 실행 중인 (
--inspect
로 시작한) Node 애플리케이션에 디버거를 연결하는 디버그 설정을 생성하세요.
명령행 옵션
다음 테이블은 디버깅용 여러 런타임 플래그의 기능을 보여줍니다.
플래그 | 의미 |
---|---|
--inspect |
|
--inspect=[host:port] |
|
--inspect-brk |
|
--inspect-brk=[host:port] |
|
node inspect script.js |
|
node inspect --port=xxxx script.js |
|
원격 디버깅 활성화 시나리오
디버거가 퍼블릭 IP 주소에서 수신하지 않는 것을 권장합니다. 만약 원격 디버깅 연결을 허용해야 하는 경우 ssh 터널링을 대신 사용할 것을 권장합니다. 설명을 위해 아래 예제를 제공합니다. 진행하기 전 권한을 가진 서비스에 원격 액세스를 허용할 경우 발생할 수 있는 보안 위험을 이해하시기 바랍니다.
디버깅하기를 원하는 remote.example.com 원격 시스템에서 노드가 실행 중이라고 가정하겠습니다. 해당 시스템에서 localhost(기본값)만 수신하는 인스펙터로 노드 프로세스를 시작해야 합니다.
node --inspect server.js
이제 디버그 클라이언트 연결을 시작하려는 로컬 시스템에서 ssh 터널을 설정할 수 있습니다.
ssh -L 9221:localhost:9229 [email protected]
그러면 로컬 시스템의 9221 포트에서 remote.example.com의 9229 포트로 전달되는 ssh 터널 세션이 시작됩니다. Chrome DevTools 또는 Visual Studio Code 등의 디버거로 localhost:9221에 연결 할 수 있으며 Node.js 애플리케이션이 로컬에서 실행 중인 것처럼 디버깅할 수 있습니다.
레거시 디버거
레거시 디버거는 Node 7.7.0부터 폐기되었습니다. 대신 --inspect와 인스펙터를 사용하세요.
버전 7 이하에서 --debug나 --debug-brk 스위치로 시작하면 Node.js는
TCP 포트(기본 5858
)로 지금은 중단된 V8 디버깅 프로토콜에서 정의한 디버깅 명령어를 받습니다.
이 프로토콜을 사용하는 모든 디버거 클라이언트는 실행된 프로세스에 접속하고 디버깅할 수 있습니다.
인기 있는 클라이언트의 목록이 아래 나와 있습니다.
V8 디버깅 프로토콜은 더는 관리되지 않고 문서화도 되지 않습니다.
내장 디버거
Node의 내장 명령형 디버거로 스크립트를 실행하려면 node debug script_name.js
로 실행하세요.
스크립트가 다른 Node 프로세스에서 --debug-brk
옵션으로 시작되고 원래의 Node 프로세스는
_debugger.js
를 실행해서 대상에 접속합니다.
node-inspector
크로미움에서 사용하는 인스펙터 프로토콜을 Node.js가 사용하는 V8 디버거 프로토콜로 변환하는 중간 프로세스를 사용해서 크롬 개발자도구로 Node.js 애플리케이션을 디버깅합니다.