개발 및 AI · Clash 기술 블로그

Git, npm 및 Docker가 Clash를 사용하지 않을 때 터미널 프록시 설정 및 시간 초과 해결

Git, npm, Docker는 프록시 설정 출처가 다르므로 터미널 변수가 docker pull을 자동으로 고치지는 않습니다. 로컬 포트를 검증한 뒤 해당 도구의 환경 변수, 구성 파일, 백그라운드 프록시를 확인하세요. 다운로드 성공 후 테스트 설정을 정리하고 종료 후 직접 연결을 확인하세요.

본문 읽기블로그로 돌아가기
  • Git
  • npm
  • Docker
  • WSL2
이 글의 목차
글 작성자
Clash 공식
게시일
업데이트 날짜
예상 읽기 시간
약 7분

터미널에 프록시 주소를 입력했는데도 다운로드가 실패한다면 도구가 실제로 읽는 설정을 확인해야 합니다. 임시 변수, 사용자 설정, 백그라운드 프로세스의 설정은 자동으로 동기화되지 않습니다. 오류를 낸 도구부터 하나씩 처리하고, 현재 프록시 포트가 정상인지 확인한 뒤 필요한 설정을 저장해 포트를 바꿀 때 설정 충돌이 남지 않도록 하세요.

Git, npm, Docker 요청을 보내는 프로세스

브라우저에서 GitHub에 접속할 수 있다고 명령줄 도구가 같은 프록시를 사용한다는 뜻은 아닙니다. Git은 자체 설정과 환경 변수를 읽고 npm은 npmrc도 읽으며, Docker Desktop과 Docker Engine은 별도의 백그라운드 프로세스를 사용합니다. 세 명령이 동시에 실패해도 각각의 프록시 설정을 확인해야 할 수 있습니다.

문제를 재현하는 명령을 각각 실행하세요. git ls-remote https://github.com/git/git.git HEAD, npm ping, docker pull hello-world를 실행하고 오류 문구를 기록합니다.

실제로 요청을 시작한 주체

도구일반적인 프록시 출처확인할 위치
Git HTTPSGit 설정 또는 HTTP(S)_PROXYgit config 및 GIT_CURL_VERBOSE
npm환경 변수, npmrc, registry 설정npm config get 및 npm ping
Docker DesktopDesktop의 Proxies 설정Desktop 로그 및 pull 오류
Linux Docker Enginedockerd의 daemon.json 또는 systemd 환경journalctl -u docker

로컬 프록시 포트가 수신 대기 중일까?

Clash 클라이언트에서 mixed-port 또는 HTTP 포트를 확인하고 습관적으로 7890이라고 가정하지 마세요. Windows에서는 netstat -ano, macOS 또는 Linux에서는 lsof, ss로 포트를 확인할 수 있습니다. 포트가 없으면 어떤 도구 설정에서도 connection refused만 발생합니다.

curl에 프록시를 명시해 알려진 HTTPS 주소에 접근하면 로컬 프록시가 작동하는지 바로 확인할 수 있습니다. 성공한 뒤 같은 포트를 Git이나 npm에 넣으세요. curl도 실패한다면 세 도구의 영구 설정을 계속 바꾸지 말고 클라이언트, 노드, 로컬 방화벽을 확인하세요.

로컬 HTTP 프록시 임시 검증
# 将 7890 换成客户端显示的 HTTP 或 mixed 端口
curl -I -x http://127.0.0.1:7890 https://github.com

# Linux 查看监听
ss -lntp | grep 7890

# Windows 查看监听
netstat -ano | findstr :7890

Could not resolve host는 이름 해석을 가리키고 Connection refused는 로컬 포트에 수신 프로세스가 없을 때 흔합니다. TLS 또는 인증서 오류는 제한 시간을 늘려 해결할 수 없습니다.

현재 터미널에만 프록시 변수 설정

HTTP_PROXY와 HTTPS_PROXY는 현재 터미널에서 시작하고 해당 변수를 읽는 프로그램에만 적용됩니다. 새 터미널에 임시로 설정해 git 또는 npm 시험을 완료한 뒤 터미널을 닫으면 저절로 사라집니다. 결과가 유효할 때 PowerShell Profile, .zshrc 또는 CI 환경에 쓸지 결정하세요.

NO_PROXY에는 localhost, 127.0.0.1, 직접 연결할 내부 도메인을 남겨야 합니다. 내부망 요청을 모두 Clash로 보내면 로컬 개발 서비스, 회사 저장소 또는 Docker 컨테이너 간 통신에 새 문제가 생깁니다.

터미널 세션 한 번의 환경 변수
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,.local

# PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

Git 프록시 설정의 출처 확인

git config --show-origin --get-regexp는 프록시가 어느 파일에서 왔는지 보여 줍니다. 출력이 없으면 보통 Git에 별도 프록시가 저장되지 않았다는 뜻이며 새 오류가 아닙니다. 기존 클라이언트가 남긴 http.proxy가 닫힌 포트를 가리키면 환경 변수가 올바르더라도 Git이 기존 값을 계속 사용할 수 있습니다.

Git HTTPS 프록시를 고정해야 할 때는 사용자 수준 http.proxy에만 쓰고 필요 없으면 --unset-all로 정리하세요. SSH remote는 Git의 HTTP 프록시를 사용하지 않습니다. [email protected] 시간 초과에서는 SSH, ProxyCommand를 별도로 확인하거나 먼저 HTTPS로 비교하세요.

Git 프록시 확인, 설정, 정리
git config --show-origin --get-regexp '(^http\..*proxy$|^remote\..*\.proxy$)'

# 需要固定代理时再写入
git config --global http.proxy http://127.0.0.1:7890
git ls-remote https://github.com/git/git.git HEAD

# 以后改回环境变量或直连时删除
git config --global --unset-all http.proxy

npm 시간 초과에서는 프록시와 registry를 구분해야 합니다

npm 공식 설정은 HTTP_PROXY, HTTPS_PROXY를 읽고 사용자 또는 프로젝트 .npmrc에 proxy, https-proxy, registry를 저장할 수도 있습니다. registry가 중단된 미러를 가리키면 프록시 노드를 바꿔도 요청 주소는 달라지지 않습니다.

npm config get proxy, npm config get https-proxy, npm config get registry를 실행한 뒤 npm ping으로 현재 registry를 검증하세요. 프로젝트 디렉터리의 .npmrc가 사용자 설정을 덮어쓸 수 있으므로 같은 컴퓨터에서도 프로젝트별로 동작이 다를 수 있습니다.

임시 환경 변수가 이미 적용되었다면 npm 고정 프록시를 다시 쓸 필요가 없습니다. npm이 환경 변수를 읽지 않았음을 확인한 뒤 아래 두 항목을 설정하세요.

npm 프록시 확인, 설정, 정리
npm config get proxy
npm config get https-proxy
npm config get registry
npm ping

# 仅在确实需要 npm 固定代理时设置
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm ping

# 改回环境变量或直连时清理
npm config delete proxy
npm config delete https-proxy

docker pull은 백그라운드 엔진이 시작하므로 현재 shell 수정이 효과 없을 수 있습니다

Docker Desktop에는 자체 프록시 설정이 있습니다. Windows 또는 macOS에서 Docker Desktop의 Settings → Resources → Proxies로 이동해 System proxy를 선택하세요.

시스템 프록시가 인식되지 않으면 Manual configuration을 선택하고 Clash의 HTTP 또는 mixed 포트를 입력하세요.

Docker 공식 안내에 따르면 Desktop은 daemon.json의 daemon proxy 설정을 읽지 않으므로 두 위치를 반복해서 함께 수정하지 마세요.

네이티브 Linux Docker Engine에서는 dockerd가 이미지를 가져옵니다. /etc/docker/daemon.json이 있는지 확인하고 아래 proxies 필드를 기존 JSON에 병합하세요. 파일 전체를 덮어쓰면 안 됩니다. 저장 후 JSON과 daemon 설정을 검증한 뒤 Docker를 다시 시작합니다.

컨테이너 내부 앱의 프록시 설정은 별도이며 daemon이 실행하는 docker pull을 반대로 고치지 못합니다.

Linux Docker Engine의 daemon 프록시
# 把 proxies 合并进现有 /etc/docker/daemon.json，不要覆盖其他字段
{
  "proxies": {
    "http-proxy": "http://127.0.0.1:7890",
    "https-proxy": "http://127.0.0.1:7890",
    "no-proxy": "localhost,127.0.0.1,.local"
  }
}

sudo dockerd --validate --config-file=/etc/docker/daemon.json
sudo systemctl restart docker
docker info | grep -i proxy
docker pull hello-world
Docker Desktop
Settings → Resources → Proxies에서 Docker Desktop proxy와 Containers proxy를 확인하세요. 설정을 적용한 뒤 hello-world를 새로 가져와 테스트합니다.
실행 중인 컨테이너
컨테이너에서 외부 네트워크에 접근해야 할 때만 프록시 변수를 전달하고, 호스트와 내부 네트워크 주소는 NO_PROXY에 지정하세요.

WSL 또는 컨테이너에 들어가면 127.0.0.1이 가리키는 주체가 바뀝니다

Windows의 Clash는 127.0.0.1에서 수신하지만 WSL2나 컨테이너 안의 127.0.0.1은 각 환경 자체를 가리킵니다. NAT 네트워크에서는 호스트에 연결할 수 있는 주소를 사용하고, 클라이언트의 LAN 연결 허용 여부와 Windows 방화벽이 필요한 가상 네트워크 대역에만 열려 있는지 확인하세요. 미러 네트워크 모드는 동작이 다르므로 현재 WSL 네트워크 설정에 맞춰 검증해야 합니다.

먼저 WSL이나 컨테이너에서 curl로 호스트 프록시 포트에 접속하세요. 포트조차 연결되지 않으면 Git이나 npm 설정을 더 바꿔도 의미가 없습니다. 포트 연결을 확인한 뒤 환경 변수를 쓸지, Clash TUN이 해당 프로세스를 맡게 할지 결정합니다.

불필요한 프록시 설정을 정리해 도구가 이전 포트에 계속 연결하지 않도록 하세요

환경 변수, Git 전역 설정, npmrc, Docker 설정이 함께 있으면 포트를 바꾸거나 클라이언트를 종료할 때 어떤 설정이 여전히 적용되는지 판단하기 어렵습니다. 평소 실제 사용하는 설정 방식은 유지하고 테스트 중 넣은 불필요한 고정 프록시는 삭제한 뒤 어떤 명령이 이에 의존하는지 기록하세요.

새 터미널을 열어 이번에 설정을 바꾼 도구만 다시 테스트하세요. Git은 git ls-remote https://github.com/git/git.git HEAD, npm은 npm ping, Docker는 docker pull hello-world를 사용합니다.

전에 실패한 명령이 결과를 반환하고 Clash 연결 페이지에 해당 요청이 표시되어야 합니다. 이번 점검을 위해 사용하지 않는 도구까지 설정할 필요는 없습니다.

Clash를 종료한 뒤에는 도구가 닫힌 로컬 포트를 계속 가리키면 안 됩니다. 여전히 Connection refused가 나타나면 남아 있는 고정 프록시 설정을 더 정리하세요.

참고 자료