지금 이 순간 Stack Overflow 어딘가에서는 누군가가 Axios가 HTTPS 프록시에서 "조용히 깨진다"고 확신하고 있을 겁니다. Node.js proxy 튜토리얼에서 가장 자주 반복되는 주장 중 하나지만, 이 글에서 검증한 현재 릴리스에는 해당하지 않습니다. 저는 실제 HTTP/HTTPS 오리진과 두 개의 프록시를 뒤에 둔 로컬 테스트 환경을 띄워봤고, Axios 1.19.0은 HTTPS 요청을 프록시를 우회하지 않고 올바른 CONNECT 요청으로 터널링했습니다.
그렇다고 사람들이 겪는 불편이 전부 과장은 아닙니다. 예전 Axios 버전에는 실제 버그가 있었고(issue #3384, issue #4531 참고), 최신 Node 릴리스에는 별도로 신경 써야 하는 환경 변수 기반 프록시 경로도 추가됐습니다. 이 가이드에서는 현재 기준 Axios 1.19.0에서 실제로 동작하는 방식, 요청에 프록시를 연결하는 모든 방법, 대부분의 튜토리얼에서 다루지 않는 인터셉터 기반 로테이션 패턴, 그리고 결국 문제가 생겼을 때 바로 찾아볼 수 있는 에러-해결표까지 차근차근 정리합니다.
Axios 프록시란 무엇이고, Node.js에서 왜 중요한가?
Axios에서 말하는 프록시는 Node 프로세스와 대상 사이트 사이에 끼어 있는 중간 서버입니다. 요청은 먼저 프록시로 가고, 프록시가 대신 전달하며, 대상 사이트는 내 IP가 아니라 프록시의 IP를 보게 됩니다. 원리는 이게 전부입니다.
개발자들이 프록시를 찾는 이유는 여러 가지입니다. IP 기준으로 속도 제한이나 차단이 걸린 사이트를 크롤링할 때, 다른 지역에서 접속한 것처럼 앱 동작을 시험할 때, 사내 egress 경로를 통해 트래픽을 보낼 때, 또는 단순히 내 서버 IP를 어떤 대상의 접근 로그에 남기고 싶지 않을 때도 사용합니다. Axios 공식 요청 설정은 host, port, protocol, auth 필드를 갖는 내장 proxy 옵션을 제공합니다. 이 옵션은 오래전부터 있었고, 모든 튜토리얼이 가장 먼저 보여주는 방식이기도 합니다.
여기서 놓치기 쉬운 핵심이 있습니다. 이 proxy 옵션은 HTTP 대상에 요청하느냐 HTTPS 대상에 요청하느냐, 그리고 사용 중인 Axios 버전이 무엇이냐에 따라 다르게 동작합니다. 이 차이 때문에 이 가이드가 필요한 겁니다.
Node.js와 Axios 기본 설정하기
이미 프로젝트가 있다면 건너뛰어도 됩니다. 없다면 2분이면 충분합니다.
mkdir axios-proxy-demo && cd axios-proxy-demo
npm init -y
npm install axios
ESM import를 쓰고 싶다면 package.json에 "type": "module"을 추가하세요. 저는 그렇게 하는 편입니다. 프록시 데모에 CommonJS require()를 쓰는 건 조금 구식처럼 느껴지니까요. 현재 Node LTS는 v24.18.0입니다만, 저는 최신 런타임 특유의 변수를 피하려고 v22.22.3에서 테스트했습니다.
이 코드를 app.js에 넣고 node app.js로 실행하세요.
import axios from 'axios';
const res = await axios.get('https://httpbin.org/ip');
console.log(res.data);
응답에서 실제 IP 주소가 보여야 합니다. 이게 기준선입니다. 프록시가 제대로 작동하면 같은 요청에서 프록시의 IP가 대신 보여야 합니다.
다음 단계에서 프록시를 켜기 전에 이 응답을 기록해 두세요. 그래야 프록시 적용 후 결과와 명확하게 비교할 수 있습니다.
Axios는 HTTPS 프록시를 실제로 지원하나요? 사실관계 정리
짧게 답하면: 네, 현재 안정 버전에서는 지원합니다. Axios 1.19.0은 HTTP 프록시 뒤의 HTTPS 대상에 대해 CONNECT 터널링을 문서화하고 있습니다. npm 다운로드 API에는 2026년 7월 31일부터 8월 6일까지 Axios가 117,890,039회 다운로드된 것으로 기록돼 있는데, 이건 라이브러리의 폭넓은 사용을 보여주는 다소 오래된 지표입니다. HTTPS URL을 프록시를 통해 요청하면, 현재 Axios는 CONNECT 요청을 보내 터널을 만들고 TLS 핸드셰이크는 실제 오리진과 종단 간으로 이루어집니다. 저는 이 동작을 직접 확인했습니다. 로컬 HTTP 프록시와 자체 서명 인증서를 사용하는 로컬 HTTPS 오리진을 세팅한 뒤, 프록시의 CONNECT 카운터가 예상대로 정확히 증가했습니다.
그렇다면 왜 "Axios HTTPS 프록시가 깨졌다"는 이야기가 거의 모든 포럼 스레드에 등장할까요? 이유는 몇 가지 있고, 모두 실제로 존재하는 문제들입니다.
- 오래된 Axios 버전. 사람들이 링크하는 GitHub 이슈는 종종 몇 년 전의 것이며, 특정 릴리스나 설정에서만 나타난 동작을 설명합니다. 이를 현재 Axios 전체에 일반화하면 안 됩니다.
- CONNECT를 지원하지 않는 프록시 서버. 이런 구성에서는 터널이 실패하고 Axios가 에러를 내야 합니다. IP 우회를 의심하기 전에 실제 경로와 에러부터 확인하세요.
proxy설정을 다른 것으로 오해하는 경우.proxy옵션은 포워드 프록시용 설정이지, "무조건 이 에이전트를 통해 모두 보내라"는 범용 스위치가 아닙니다.
Chromium은 2023년에 주요 플랫폼의 Chrome 탐색 중 90% 이상이 HTTPS를 사용한다고 보고했습니다. 이는 현재 전체 웹의 최신 통계라기보다 다소 지난 Chrome 측정치이지만, HTTPS 대상 동작이 이 튜토리얼의 중심에 있어야 하는 이유를 잘 보여줍니다. 오래된 Axios 릴리스를 쓰고 있다면, 과거 이슈가 지금도 그대로 맞는다고 가정하지 말고 현재 라인에서 문제를 재현해 보세요. 실제 배포 전에 본인 애플리케이션에서 업그레이드를 먼저 검증하는 것이 안전합니다.
그래도 명시적인 에이전트가 필요한 경우
네이티브 proxy 설정은 단일하고 고정된 일반 프록시 하나를 쓰는 경우에는 충분합니다. 하지만 요청별 제어, 프록시 로테이션, SOCKS 지원이 필요해지는 순간 금방 한계에 부딪힙니다. Axios의 내장 옵션은 그런 용도로 만들어지지 않았기 때문입니다. 이럴 때 HttpsProxyAgent가 제 역할을 합니다. 아래에서 자세히 살펴보겠습니다. 네이티브 옵션은 "프록시 하나, 목적 하나면 충분"에 가깝고, 에이전트 기반 방식은 "실서비스에서 실제로 필요한 방식"이라고 생각하면 됩니다.
Node v24 및 v22.21+의 환경 프록시 경로
최근 Node 릴리스에는 NODE_USE_ENV_PROXY=1 또는 --use-env-proxy 플래그로 활성화되는 내장 환경 프록시 모드가 포함되어 있습니다. Node CLI 문서에 따르면 이 기능은 v24.0.0에 들어왔고 v22.21.0으로 백포트되었습니다. 따라서 "Node 22+"라고 뭉뚱그리는 건 정확하지 않고, 해당 라인 중에서도 v22.21.0 이상이 맞습니다. 더 이른 Node 22 패치에서는 이 플래그가 아예 없습니다.
현재 Axios는 이미 proxy-from-env 의존성을 통해 HTTP_PROXY, HTTPS_PROXY, NO_PROXY를 해석합니다. 따라서 현재 Axios 경로에서는 global-agent가 필요하지 않습니다. 다만 Node 자체의 env-proxy 모드가 동시에 켜져 있으면, 라우팅 결정에 두 계층이 관여할 수 있습니다.
Axios 문서에 따르면 agent가 proxyEnv 속성을 갖는 Node 버전에서는 Axios가 자체 해석 대신 Node의 처리를 따릅니다. 실무적으로는 한 시스템만 선택해서 일관되게 쓰는 것이 좋습니다.
- Node에 맡기기: 플래그를 켜고, Axios의
proxy설정은 건드리지 말고, 환경 변수가 라우팅을 담당하게 합니다. - Axios에 맡기기: Node 플래그를 켜지 말고, Axios의 환경 변수 해석이 동작하게 둡니다.
- 완전 수동 제어:
proxy: false를 명시하고 직접httpsAgent를 넣습니다. 로테이션이나 요청별 로직이 필요해지면 이 방식이 자동 시스템 둘을 모두 우회하기 때문에 가장 권장됩니다.
저는 Axios 쪽 해석도 직접 검증했습니다. 자식 프로세스 환경에 HTTP_PROXY를 넣자 요청이 로컬 프록시를 거쳤고, 대응하는 NO_PROXY 항목을 추가하자 다음 요청은 정상적으로 프록시를 건너뛰었습니다. 즉, 현재는 환경 변수 경로가 실제로 바로 동작합니다. 다만 주의할 것은 이중 모드가 동시에 활성화되는 상황입니다.
Axios에 프록시를 연결하는 5가지 방법 비교
코드로 들어가기 전에 전체 그림부터 보겠습니다. 아래 방식들은 문서만 읽은 것이 아니라, 실제 로컬 프록시 환경에서 하나씩 만들어 보고 테스트한 것입니다.
| 방식 | HTTPS 지원 | 인증 지원 | 요청별 제어 | 로테이션 적합성 | 복잡도 |
|---|---|---|---|---|---|
인라인 proxy 옵션 | ✅ (현재 Axios) | ✅ | ✅ | ❌ | 낮음 |
axios.create() 기본값 | ✅ (현재 Axios) | ✅ | ❌ (인스턴스 전체) | ❌ | 낮음 |
환경 변수 (HTTP_PROXY/HTTPS_PROXY) | ✅ | ✅ | ❌ | ❌ | 낮음 |
httpsAgent + HttpsProxyAgent | ✅ | ✅ | ✅ | ⚠️ (수동) | 중간 |
| 요청 인터셉터 + 에이전트 풀 | ✅ | ✅ | ✅ | ✅ | 중간-높음 |
단발성 스크립트에서 하나의 프록시를 향해 요청할 때는 인라인 옵션을 쓰세요. 모듈 안의 모든 요청이 같은 프록시를 써야 하고 설정을 반복하고 싶지 않다면 axios.create()가 좋습니다. 인프라 팀이 이미 프록시 라우팅을 중앙에서 관리하고 있어서 그냥 그 설정을 물려받고 싶다면 환경 변수를 쓰면 됩니다. 네이티브 설정으로는 부족한 제어가 필요할 때는 명시적인 에이전트를 쓰고, "제어"가 곧 "로테이션"을 뜻하게 되는 순간에는 인터셉터 패턴으로 넘어가세요.
단계별: Axios 기본 프록시 설정
가장 단순한 구성은 요청에 내장 proxy 객체를 직접 넣는 방식입니다.
import axios from 'axios';
const res = await axios.get('https://httpbin.org/ip', {
proxy: {
host: '203.0.113.10',
port: 8080,
protocol: 'http',
},
});
console.log(res.data);
이 코드를 실행하면 응답에 내 IP 대신 프록시의 IP가 보여야 합니다. 실제 프록시로 로컬 테스트를 한다면 보통 1초도 안 걸려 끝납니다. 단 하나의 요청을 시험하려고 시스템 전체 프록시를 직접 바꾸는 것과 비교하면 훨씬 간단합니다. 그런 건 금세 15분을 잡아먹습니다.
이 응답을 기준선과 비교하세요. 성공적인 테스트라면 앞서 기록한 오리진 IP가 아니라 프록시의 공인 IP가 보여야 합니다.
axios.create()로 인스턴스 전체 기본값 적용하기
특정 모듈의 모든 요청이 같은 프록시를 사용해야 한다면, 매번 설정을 반복하지 말고 인스턴스에 기본값을 넣으세요.
const client = axios.create({
proxy: {
host: '203.0.113.10',
port: 8080,
},
timeout: 15_000,
});
const res = await client.get('https://httpbin.org/ip');
개별 요청에서 proxy: false로 덮어쓰면 인스턴스 기본값을 깔끔하게 우회할 수 있는 것도 확인했습니다. 예를 들어 호출의 95%는 프록시가 필요하지만, 일부 요청(예: 헬스체크 ping)은 프록시를 타면 안 되는 경우에 유용합니다.
환경 변수를 이용해 프록시 설정하기
Docker 컨테이너나 CI 환경처럼 운영 팀이 이미 프록시 환경 변수를 관리하는 경우에는 Axios 설정을 건드릴 필요가 없습니다.
export HTTP_PROXY=http://203.0.113.10:8080
export HTTPS_PROXY=http://203.0.113.10:8080
export NO_PROXY=localhost,127.0.0.1
현재 Axios는 global-agent 없이도 이 변수들을 읽습니다. 다만 앞서 언급한 Node 버전 경계는 기억하세요. NODE_USE_ENV_PROXY도 함께 활성화되어 있다면, 어떤 계층이 라우팅의 주체인지 명확히 하고 실제 배포 런타임에서 NO_PROXY 동작을 테스트해야 합니다.
단계별: httpsAgent로 HTTPS 프록시 설정하기 (실제 제어가 필요할 때)
프록시가 하나로 고정되지 않는 순간부터는 제가 실제로 추천하는 방식입니다. 에이전트 패키지를 설치하세요.
npm install https-proxy-agent
https-proxy-agent 9.1.0은 Node 20 이상이 필요하며, 대상 연결을 터널링하기 전에 프록시로 올바른 CONNECT 요청을 보냅니다.
import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';
const agent = new HttpsProxyAgent('http://203.0.113.10:8080');
const client = axios.create({
proxy: false, // Axios의 네이티브 해석이 같이 개입하지 않도록 함
httpsAgent: agent,
timeout: 15_000,
});
const res = await client.get('https://httpbin.org/ip');
console.log(res.data);
명시적인 에이전트가 라우팅을 담당할 때는 proxy: false를 설정하세요. 그래야 설정 의도가 분명해지고, Axios의 네이티브 혹은 환경 기반 프록시 해석이 전달된 에이전트와 충돌하지 않습니다.
프록시 인증 추가하기
인증 정보는 프록시 URL에 바로 넣을 수 있습니다.
const agent = new HttpsProxyAgent('http://myuser:mypassword@203.0.113.10:8080');
비밀번호에 @, :, # 같은 특수문자가 있다면 URL로 만들기 전에 퍼센트 인코딩을 하세요. 아니면 각 구성 요소에 encodeURIComponent()를 적용해 문자열을 조립하면 됩니다. 비밀번호에 들어간 @를 그대로 두면 호스트 섹션의 시작으로 해석되어, 인코딩 문제와는 전혀 상관없어 보이는 연결 오류를 만나게 됩니다.
Axios에서 SOCKS5 프록시 사용하기
SOCKS 프록시는 HttpsProxyAgent와 호환되지 않으므로, 프로토콜에 맞는 다른 에이전트가 필요합니다.
npm install socks-proxy-agent
import { SocksProxyAgent } from 'socks-proxy-agent';
const agent = new SocksProxyAgent('socks5://myuser:mypass@203.0.113.10:1080');
const client = axios.create({
proxy: false,
httpsAgent: agent,
});
socks-proxy-agent 10.1.0 역시 Node 20+가 필요합니다. SOCKS5는 기업 네트워크에서 SOCKS 게이트웨이만 노출하는 경우나, 일반 HTTP 프록시보다 더 유연한 프로토콜 지원을 제공하는 프록시 업체를 사용할 때 특히 유용합니다.
Axios 요청 인터셉터로 프록시 로테이션하기
호출 코드 안에서 랜덤 프록시를 고르는 방식은 한 번성 스크립트에는 괜찮습니다. 하지만 수백 건의 요청을 보내기 시작하면 금방 무너집니다. 죽은 프록시를 추적하는 중앙 관리 지점도 없고, 재시도 로직도 없고, 프록시 선택 코드가 여기저기 복붙되기 때문입니다. Axios의 인터셉터 시스템은 이 로직을 테스트 가능한 한 곳에 모아 줍니다. 이 글의 SERP 검토에서 본 경쟁 튜토리얼 다섯 개는 모두 이 패턴을 쓰지 않았습니다.
프록시 풀 만들기
import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';
class ProxyPool {
private agents: HttpsProxyAgent<string>[];
private index = 0;
constructor(proxyUrls: string[]) {
this.agents = proxyUrls.map((url) => new HttpsProxyAgent(url));
}
next(): HttpsProxyAgent<string> {
const agent = this.agents[this.index];
this.index = (this.index + 1) % this.agents.length;
return agent;
}
}
const pool = new ProxyPool([
'http://user:pass@proxy1.example.com:8080',
'http://user:pass@proxy2.example.com:8080',
]);
const client = axios.create({ timeout: 15_000 });
client.interceptors.request.use((config: InternalAxiosRequestConfig) => {
config.proxy = false;
config.httpsAgent = pool.next();
return config;
});
저는 이 코드를 두 개의 로컬 프록시로 테스트했고, 요청이 A 프록시, B 프록시, 다시 A 프록시 순으로 정확히 번갈아 가는 것을 확인했습니다. 참고로 Axios는 요청 인터셉터를 후입선출(LIFO)로 실행하므로, 인증 헤더나 로깅 같은 다른 인터셉터가 있다면 순서가 생각보다 중요합니다.
재시도 가드를 둔 응답 인터셉터 추가하기
대부분의 DIY 로테이션 스크립트가 허술해지는 지점이 여기입니다. 실패할 때마다 무한정 재시도하면, 특히 POST처럼 다시 보내면 안 되는 요청에서 하나의 실패가 연쇄적인 문제로 커질 수 있습니다. 재시도 자체가 원치 않는 부작용을 두 번 만들 수도 있습니다.
type RetryableConfig = InternalAxiosRequestConfig & {
__proxyRetryCount?: number;
};
client.interceptors.response.use(
undefined,
async (error: AxiosError) => {
const config = error.config as RetryableConfig | undefined;
if (!config) throw error;
const method = String(config.method ?? 'get').toUpperCase();
config.__proxyRetryCount ??= 0;
if (method !== 'GET' || config.__proxyRetryCount >= 1) throw error;
config.__proxyRetryCount += 1;
config.proxy = false;
config.httpsAgent = pool.next();
return client.request(config);
}
);
저는 일부러 고장 난 프록시로 이 코드를 테스트했고, 대체 에이전트로 정확히 한 번만 재시도가 일어나는 것을 확인했습니다. 무한 루프도 없었고, POST 요청도 재시도되지 않았습니다. 이 정도가 적절한 한도입니다. 어떤 요청이 안전하게 다시 보낼 수 있는지 솔직하게 판단하는 재시도 정책이어야지, "될 때까지 다시 시도"하는 식의 땜질은 곤란합니다.
에러 진단표: 모든 실패를 해결책과 연결하기
이 표는 꼭 저장해 두세요. Axios GitHub 이슈와 Stack Overflow 스레드에 실제로 등장하는 오류들만 모았습니다. 가상의 에러가 아닙니다.
| 오류 / 증상 | 가능한 원인 | 해결 방법 |
|---|---|---|
ECONNREFUSED | host/port가 틀렸거나 프록시 서버가 다운됨 | Axios 코드를 건드리기 전에 curl -x http://host:port target-url로 먼저 확인 |
407 Proxy Authentication Required | 인증 정보가 없거나 잘못됨 | proxy 설정에 auth: { username, password }를 추가하거나, HttpsProxyAgent URL에 자격 증명을 포함 |
403 Forbidden | 오리진 또는 WAF가 요청이나 프록시 IP를 거부함 | 사이트의 접근 정책, 인증, 요청 빈도를 확인하세요. 다른 헤더나 IP를 쓴다고 제한을 우회할 권한이 생기는 것은 아닙니다 |
| 응답에 내 실제 IP가 표시됨 | NO_PROXY, proxy:false, 명시적 직결 에이전트, 혹은 과거/버전별 설정이 프록시를 우회 중 | 어떤 계층이 라우팅을 담당하는지 확인하고, 필요하면 제어된 IP 엔드포인트와 명시적 에이전트로 경로를 검증 |
ETIMEDOUT | 연결 또는 응답 시간이 설정된 timeout을 초과함 | 어디에서 시간이 쓰이는지 측정하고, 워크로드가 정당화될 때만 timeout을 늘리세요. 아니면 문제 있는 경로를 교체하거나 식혀야 합니다 |
응답 도중 ECONNRESET | 프록시, 네트워크, 또는 오리진이 연결을 끊음 | 실패한 홉을 기록하고, 다시 보내도 안전한 요청만 제한적으로 재시도 |
Nginx 뒤에서 502 Bad Gateway | Nginx의 proxy_pass 설정이 잘못됐거나 Axios의 timeout과 Nginx 설정이 맞지 않음 | proxy_connect_timeout 및 proxy_read_timeout 값을 확인하고(A 기본값은 60초), Axios timeout과 맞추세요 |
ERR_TLS_CERT_ALTNAME_INVALID | 대상에 맞지 않는 에이전트를 사용했거나 자체 서명 인증서임 | 프로토콜에 맞는 에이전트를 쓰고 있는지 확인하세요. 로컬 테스트에서만 rejectUnauthorized: false를 사용하고, 운영에서는 절대 쓰지 마세요 |
빠른 디버깅 체크리스트
문제가 생겼는데 이유를 바로 알 수 없다면, 아래 순서대로 점검하세요.
curl -x http://host:port https://your-target.com으로 프록시를 직접 테스트하세요. 실패하면 Axios를 바꾸기 전에 프록시 연결, 인증, 대상 사이트를 먼저 확인해야 합니다. 성공하면 Axios 경로도 별도로 검증해야 합니다.- 실제로 어떤 Axios와 Node 버전을 쓰는지 확인하고, 과거 사례를 같은 릴리스/같은 설정 기준으로 비교한 뒤에만 해결책을 적용하세요.
- 어떤 시스템이 프록시를 해석하는지 파악하세요. 네이티브 Axios 설정인지, Axios의 환경 변수 해석인지, Node의 내장 env-proxy 모드인지, 아니면 명시적 에이전트인지 구분해야 합니다. 하나의 요청을 두 계층이 동시에 소유하게 두면 안 됩니다.
NO_PROXY에 실수로 호스트명이 매칭되는 경우가 없는지 확인하세요.- 명시적 에이전트를 쓰고 있다면
proxy: false가 설정되어 있는지 확인해서 Axios가 이중 처리하지 않도록 하세요.
DIY 프록시 구성을 아예 건너뛰어야 할 때
지금까지의 내용은 실제 목표가 임의 트래픽 라우팅일 때, 예를 들어 사내 네트워크 테스트나 지역별 앱 테스트, 통제된 네트워크 egress가 필요할 때는 분명 유용합니다. 하지만 많은 개발자들이 "Axios 프록시를 어떻게 설정하지?"를 검색하는 진짜 이유는 웹사이트에서 데이터를 가져오고 싶기 때문이고, 프록시는 그 수단일 뿐입니다.
그렇다면 정말 프록시가 필요한지, 아니면 인프라를 대신 처리해 주는 스크래핑 API가 필요한지 생각해 볼 만합니다. Thunderbit의 Open API는 URL과 스키마만 넣으면 구조화된 JSON을 반환합니다. 원시 HTML 파싱도 없고, 에이전트 라이브러리도 없고, 관리해야 할 프록시 풀도 없습니다. /extract 엔드포인트는 JS 렌더링 페이지, 봇 차단, CAPTCHA를 서버 측에서 처리하고, 페이지를 깨끗한 Markdown으로만 바꾸면 되는 경우에는 더 가벼운 /distill 엔드포인트를 사용할 수 있습니다. 또한 MCP 서버에서는 thunderbit_extract, thunderbit_suggest_fields 같은 도구를 제공하므로 Claude나 Cursor 같은 코딩 어시스턴트가 프록시 설정을 건드리지 않고도 작업 중간에 구조화 데이터를 가져올 수 있습니다. 여기에 CLI까지 있어 터미널과 CI 워크플로우에도 바로 붙일 수 있습니다.
| 관점 | DIY Axios + 프록시 | Thunderbit API/MCP/CLI |
|---|---|---|
| 프록시 소싱 및 로테이션 | 직접 관리 | 서버 측에서 처리 |
| 브라우저 및 접근 제약 대응 | 브라우저/네트워크 계층을 직접 운영 | 서비스가 문서화된 범위 내에서 관리 |
| JS 렌더링 페이지 | 헤드리스 브라우저 필요 | renderMode: full |
| 출력 형식 | 원시 HTML → 직접 파싱 | 스키마 기반 구조화 JSON |
| 사이트 변경 시 유지보수 | 파싱/셀렉터를 직접 유지 | 관리형 추출 계층이 일부 애플리케이션 유지보수를 줄여 줌 |
솔직하게 정리하면 이렇습니다. 테스트나 사내 네트워킹을 위해 트래픽을 라우팅해야 한다면 Axios와 프록시 설정을 대체할 것은 없습니다. 반대로 최종 산출물이 구조화된 웹 데이터라면, API 우선 접근 방식이 애플리케이션이 떠안아야 할 프록시, 브라우저, 파싱 코드를 줄여 줄 수 있습니다. 2026년 8월 7일 기준으로 확인했을 때 Thunderbit API의 속도 제한 문서는 Free 요금제에 분당 10회 요청, 동시 2회 요청을 명시하고 있었습니다. 이런 값은 시점에 민감하므로, 운영에 사용하기 전에 페이지를 다시 확인하세요.
마무리
핵심은 오래된 튜토리얼이 말하는 내용과 조금 다릅니다. 현재 Axios는 문서상으로도, 그리고 제가 기록한 로컬 테스트에서도 HTTPS 대상에 대해 CONNECT 터널링을 올바르게 사용했습니다. 과거의 실패 사례는 여전히 중요하지만, 버전과 설정 맥락이 필요합니다. 네이티브 설정은 복잡도가 낮은 좋은 출발점입니다. 하지만 요청별 제어, SOCKS 지원, 로테이션이 필요해지면 proxy: false와 함께 명시적인 HttpsProxyAgent(또는 SocksProxyAgent)를 쓰는 편이 소유권이 더 분명합니다. 그리고 운영 환경에서 프록시 풀을 돌릴 때는 요청/응답 인터셉터가 중앙화되고 테스트 가능한 위치가 됩니다. 다만 재시도 로직에는 반드시 루프 방지 장치를 두고, 실제로 다시 보내도 안전한 요청만 재전송하세요.
다음 번 새벽 2시에 프록시 설정이 이해하기 어려운 에러를 뱉으면 위의 진단표를 다시 보세요. 그리고 프록시 배관을 디버깅하느라 실제 데이터를 쓰는 시간보다 더 많은 시간을 쓰고 있다면, API 우선 추출 도구가 인프라보다 훨씬 빨리 문제를 해결해 줄지 확인해 볼 가치가 있습니다.
자주 묻는 질문
Axios는 HTTPS 프록시를 기본적으로 지원하나요? 현재 Axios에서는 일반적인 HTTP 프록시를 통해 지원합니다. 현재 문서는 HTTPS 대상에 대한 CONNECT 터널링을 설명하고 있으며, Axios 1.19.0은 기록된 로컬 테스트에서도 그 경로를 정상 통과했습니다. 다만 과거 릴리스와 특정 프록시 구성에서는 실제 실패 사례가 있었으므로, 무조건 성공하거나 무조건 실패한다고 가정하지 말고 정확한 버전과 프록시를 확인해야 합니다.
Axios에서 프록시를 어떻게 로테이션하나요?
각 요청을 보내기 전에 요청 인터셉터로 프록시 풀에서 다른 httpsAgent를 할당하고, 실패한 요청을 다른 프록시로 다시 시도하는 응답 인터셉터를 함께 사용하세요. 재시도 로직은 반드시 제한해야 합니다. 예를 들어 GET 같은 멱등성 요청에 한해 한 번만 재시도해야, 다시 보내면 안 되는 요청이 실수로 반복되지 않습니다.
Axios 프록시에서 왜 내 실제 IP가 보이나요?
NO_PROXY, proxy:false, 명시적 직결 에이전트, 혹은 배포 환경별 라우팅이 프록시를 우회했는지 확인하세요. Axios/Node 버전을 기록하고, cURL로 프록시를 독립적으로 테스트하세요. 요청별로 명확한 라우팅이 필요하다면 proxy:false와 함께 HttpsProxyAgent를 쓰고, 제어된 엔드포인트에서 관측된 IP를 확인하세요.
Axios에서 SOCKS5 프록시를 사용할 수 있나요?
네, socks-proxy-agent 패키지를 통해 가능합니다. SOCKS URL로 SocksProxyAgent 인스턴스를 만들고 Axios 설정의 httpsAgent로 넘기면 됩니다. 다만 HttpsProxyAgent를 동시에 넣으면 안 됩니다. 두 프로토콜은 서로 다른 에이전트 타입을 사용합니다.
Axios에서 proxy 옵션과 httpsAgent의 차이는 무엇인가요?
proxy 옵션은 Axios 내장 설정으로, 단일하고 고정된 프록시를 쓰는 경우에 적합하며 현재 버전에서는 간단한 용도에 잘 맞습니다. 반면 httpsAgent는 HttpsProxyAgent나 SocksProxyAgent 같은 커스텀 Node.js 에이전트를 받아 라우팅, 인증, 로테이션을 요청 단위로 직접 제어할 수 있게 해 줍니다. 이런 유연성은 네이티브 proxy 옵션이 원래 설계되지 않았던 영역입니다.
