node-sass를 설치할 때 발생하는 대표적인 오류는 Windows 환경에서 네이티브 바이너리를 직접 컴파일해야 하는 상황에서 나타난다. 다음은 실제로 마주할 수 있는 에러 로그의 핵심 부분이다.

주요 에러 메시지

Cannot download "https://github.com/sass/node-sass/releases/download/v3.8.0/win32-x64-48_binding.node":
tunneling socket could not be established, cause=socket hang up

위 메시지는 GitHub에서 사전 빌드된 바이너리를 다운로드하지 못했음을 의미한다. 이 경우 node-sass는 소스 코드에서 직접 빌드를 시도하며, 이 과정에서 다음과 같은 추가 오류가 발생한다.

gyp verb `which` failed Error: not found: python2
...
MSBUILD : error MSB3428: 未能加载 Visual C++ 组件"VCBuild.exe"

문제는 두 가지로 정리된다.

1. Python 2.x 미설치: node-gyp가 Python 실행 파일을 찾지 못함
2. Visual C++ 빌드 도구 부재: Windows에서 네이티브 애드온을 컴파일할 환경이 구축되지 않음

해결 방법

1. node-gyp 전역 설치

npm install -g node-gyp

2. Windows 빌드 도구 설치

npm install --global --production windows-build-tools

실행 중 MSI 설치 파일이 다운로드된 후 진행이 멈춘다면, %temp% 디렉터리에서 해당 MSI 파일을 직접 실행하여 설치한 뒤 위 명령을 다시 시도한다.

3. 대안: node-sass 대신 dart-sass 사용

node-sass는 LibSass 기반이며 더 이상 권장되지 않는다. 새로운 프로젝트라면 다음과 같이 교체하는 것을 고려한다.

npm uninstall node-sass
npm install -D sass

이후 webpack이나 vite 설정에서 node-sass 대신 sass를 참조하도록 변경한다.

// webpack.config.js 예시
module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              implementation: require('sass'), // dart-sass 명시
            },
          },
        ],
      },
    ],
  },
};

프록시 환경 추가 설정

기업 내부망 등에서 프록시를 통해야 하는 경우, 다음 환경 변수를 설정한다.

# PowerShell
$env:HTTP_PROXY="http://proxy.example.com:8080"
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

요약