Thiết lập proxy trong Node.js: axios, got, fetch và undici (Hướng dẫn 2026)

Mỗi HTTP client của Node.js xử lý proxy theo cách khác nhau, và một nửa trong số đó không xử lý xác thực proxy chút nào nếu không có gói trợ giúp. axios âm thầm bỏ qua tùy chọn proxy của chính nó với mục tiêu HTTPS trong một số phiên bản, fetch gốc hoàn toàn không có tùy chọn proxy nào, và các thông báo lỗi — ECONNRESET, 407, hoặc chỉ là treo — chẳng nói cho bạn điều gì.

Đây là tài liệu tham khảo đầy đủ, hoạt động được để định tuyến axios, got, node-fetch, fetch gốc (undici), và superagent qua proxy residential có xác thực. Đây là người bạn đồng hành Node của các hướng dẫn Python của chúng tôi (requests/httpx/aiohttp, Scrapy). Tất cả ví dụ đều dùng định dạng placeholder chuẩn — hãy thay bằng thông tin đăng nhập thật của bạn:

socks5h://USERNAME:[email protected]:913

Quy tắc duy nhất ngăn được hầu hết các lỗi

Đừng dùng các tùy chọn proxy tích hợp sẵn. Hãy dùng một proxy agent. Các HTTP client của Node ủy thác việc xử lý kết nối cho một đối tượng "agent", và các gói agent (https-proxy-agent, socks-proxy-agent) triển khai đường hầm CONNECT và xác thực một cách chính xác. Các tùy chọn tích hợp sẵn thường thì không — cấu hình proxy của axios là ví dụ khét tiếng nhất.

npm install socks-proxy-agent https-proxy-agent

axios

const axios = require("axios");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const res = await axios.get("https://api.ipify.org?format=json", {
  httpAgent: agent,    // for http:// targets
  httpsAgent: agent,   // for https:// targets
  proxy: false,        // IMPORTANT: disable axios's own proxy handling
});
console.log(res.data); // -> the proxy's exit IP

Hai điều mọi người hay bỏ sót: bạn phải đặt cả hai httpAgent và httpsAgent (axios chọn theo scheme của mục tiêu), và bạn phải đặt proxy: false để axios không đồng thời cố áp các biến môi trường HTTP_PROXY đè lên agent của bạn.

got

const got = require("got");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const body = await got("https://api.ipify.org?format=json", {
  agent: { http: agent, https: agent },
}).json();

Nếu bạn đang scraping các mục tiêu được bảo vệ bằng got, hãy xem got-scraping thay vào đó — cùng API, cộng thêm việc sinh header giống trình duyệt và mô phỏng vân tay HTTP/2 (tại sao điều đó quan trọng: giải thích JA3/JA4).

fetch gốc / undici (Node 18+)

fetch tích hợp sẵn của Node đến từ undici, bỏ qua các biến môi trường proxy, và không có tùy chọn agent. Cách của undici là dùng một dispatcher:

const { ProxyAgent } = require("undici");

// undici's ProxyAgent speaks HTTP CONNECT (use your HTTP proxy port)
const dispatcher = new ProxyAgent({
  uri: "http://us.jibaoproxy.com:1000",
  token: "Basic " + Buffer.from("USERNAME:PASSWORD").toString("base64"),
});

const res = await fetch("https://api.ipify.org?format=json", { dispatcher });
console.log(await res.json());

Lưu ý: ProxyAgent của undici chỉ dành cho HTTP proxy. Với SOCKS5 và fetch gốc, hoặc đặt trước nó một bộ chuyển tiếp (forwarder) cục bộ, hoặc dùng một client chấp nhận socks agent (axios/got ở trên).

node-fetch (v2/v3)

const fetch = require("node-fetch");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const res = await fetch("https://api.ipify.org?format=json", { agent });

Xoay vòng: Danh tính mới mỗi yêu cầu vs Phiên sticky

Với một gateway residential xoay vòng, bạn không phải quản lý danh sách IP — gateway giao cho bạn một điểm thoát mới mỗi kết nối, hoặc giữ một điểm thoát cho mỗi session id. Trong Node điều đó ánh xạ gọn gàng thành một agent cho mỗi danh tính:

// Sticky: same session id -> same exit IP across requests
function identityAgent(sessionId) {
  return new SocksProxyAgent(
    `socks5h://USERNAME-session-${sessionId}:[email protected]:913`
  );
}

// Account A keeps IP A, account B keeps IP B - cookies and IP move together
const agentA = identityAgent("acct_a");
const agentB = identityAgent("acct_b");

Hãy tái sử dụng agent để gộp kết nối (connection pooling) trong cùng một danh tính; không bao giờ chia sẻ một agent giữa các danh tính. Khi nào xoay vòng và khi nào giữ cố định là một chủ đề riêng — xem phiên sticky vs xoay vòng.

Bảng khắc phục sự cố

Triệu chứng	Nguyên nhân	Cách khắc phục
407 Proxy Authentication Required	Thông tin đăng nhập không đến được proxy	Đặt user:pass trong URL của agent, không phải trong cấu hình client
axios chạy trên http://, lỗi trên https://	Chỉ đặt httpAgent	Đặt cả httpsAgent, và proxy: false
ECONNRESET ngay lập tức	Sai cổng / sai giao thức (cổng HTTP với SOCKS agent)	Khớp loại agent với cổng
Rò rỉ DNS / hostname nội bộ lỗi	socks5:// phân giải DNS cục bộ	Dùng socks5h:// — chữ h gửi hostname qua proxy
fetch gốc bỏ qua HTTP_PROXY	undici không đọc biến môi trường	Truyền một dispatcher một cách tường minh
Chạy được cục bộ, 403 trên trang mục tiêu	Không phải lỗi proxy — vân tay TLS	got-scraping hoặc một trình duyệt thật; xem hướng dẫn TLS

Tóm tắt

• Luôn dùng các gói agent (socks-proxy-agent / https-proxy-agent); không bao giờ tin các tùy chọn proxy tích hợp sẵn.
• axios: cả hai agent + proxy: false. got: agent: {http, https}. fetch gốc: dispatcher ProxyAgent của undici.
• Dùng socks5h:// để DNS phân giải qua proxy — không rò rỉ.
• Một agent cho mỗi danh tính: các session id sticky giữ cookie và IP thoát di chuyển cùng nhau.
• Vẫn bị chặn dù proxy hoạt động? Đó là vân tay (fingerprinting), không phải proxy — chuyển sang got-scraping hoặc một trình duyệt.