Node Fetch Proxy: Cách cấu hình, xoay IP và xử lý lỗi

Khi gửi request bằng node-fetch, lưu lượng mạng mặc định đi thẳng từ máy chủ Node.js đến website đích. Nếu muốn request đi qua proxy, bạn cần tạo một proxy agent rồi truyền agent đó vào fetch().

Cách phổ biến với proxy HTTP hoặc HTTPS là kết hợp node-fetch và https-proxy-agent:

import fetch from 'node-fetch';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent(
  'http://username:password@proxy-host:port'
);

const response = await fetch('https://httpbin.org/ip', {
  agent
});

console.log(await response.json());

Phần quan trọng nhất là thuộc tính agent. node-fetch không có trường cấu hình proxy riêng. Agent chịu trách nhiệm mở kết nối đến proxy, tạo đường hầm khi cần rồi chuyển request đến website đích.

Bài viết này hướng dẫn từ bước cài đặt đến xác thực, xoay IP, timeout và sửa các lỗi thường gặp. Nếu chưa quen với khái niệm IP trung gian, bạn nên đọc trước bài proxy là gì và proxy hoạt động như thế nào.

node-fetch có hỗ trợ proxy trực tiếp không?

node-fetch không cung cấp tùy chọn dạng proxy: {} như một số thư viện HTTP khác.

Thay vào đó, thư viện có thuộc tính agent. Theo tài liệu chính thức, thuộc tính này nhận một http.Agent, https.Agent hoặc hàm trả về agent phù hợp với URL hiện tại.

Để kết nối qua proxy, bạn cần một thư viện agent tương ứng:

  • https-proxy-agent cho proxy HTTP hoặc HTTPS

  • socks-proxy-agent cho SOCKS4 và SOCKS5

  • proxy-agent nếu ứng dụng cần tự chọn agent theo giao thức

  • Agent riêng nếu doanh nghiệp sử dụng cấu hình mạng đặc thù

Dù tên là HttpsProxyAgent, lớp này có thể kết nối đến website HTTP và HTTPS thông qua một proxy HTTP hoặc HTTPS. Với website HTTPS, agent thường tạo đường hầm bằng phương thức CONNECT.

Phân biệt node-fetch và fetch có sẵn trong Node.js

Đây là điểm dễ gây nhầm lẫn nhất.

node-fetch là một package độc lập. Thư viện dùng hệ thống http.Agent và https.Agent của Node.js, vì vậy có thể nhận HttpsProxyAgent qua thuộc tính agent.

Node.js hiện cũng có hàm fetch() tích hợp dựa trên Undici. Hàm này không sử dụng thuộc tính agent theo cùng cách với node-fetch. Nếu chuyển đoạn mã từ node-fetch sang native fetch, cấu hình proxy có thể không còn tác dụng.

Với native fetch, bạn cần dùng dispatcher của Undici, chẳng hạn ProxyAgent hoặc EnvHttpProxyAgent, tùy phiên bản Node.js và cách triển khai.

Bài này tập trung vào package node-fetch. Các đoạn mã dưới đây không nên được sao chép nguyên trạng sang native fetch nếu chưa đổi phần agent.

Chuẩn bị môi trường Node.js

Tạo một project mới và cài các package cần thiết:

npm init -y
npm install node-fetch https-proxy-agent dotenv

node-fetch phiên bản 3 sử dụng ES Modules. Bạn có thể thêm trường sau vào package.json:

{
  "type": "module"
}

Sau đó tạo tệp index.js.

Nếu project vẫn sử dụng CommonJS với require(), cần kiểm tra phiên bản node-fetch đang cài. Phiên bản 3 là ESM-only, trong khi phiên bản 2 vẫn hỗ trợ CommonJS.

Không nên hạ phiên bản chỉ để sao chép một đoạn mã cũ. Trước tiên hãy kiểm tra cấu trúc module của project và các yêu cầu bảo trì hiện tại.

Cách dùng proxy không có tài khoản

Nếu proxy chỉ yêu cầu địa chỉ IP và port, cấu hình khá ngắn:

import fetch from 'node-fetch';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl = 'http://127.0.0.1:8080';
const agent = new HttpsProxyAgent(proxyUrl);

const response = await fetch('https://httpbin.org/ip', {
  agent
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const data = await response.json();
console.log(data);

Kết quả trả về phải hiển thị IP của proxy thay vì IP mạng đang chạy ứng dụng.

Bạn cũng có thể dùng Proxy Checker của Proxify để kiểm tra trước trạng thái, giao thức và khả năng kết nối của proxy.

Cấu hình proxy có username và password

Proxy dùng riêng thường có thông tin theo dạng:

IP:PORT:USERNAME:PASSWORD

Khi đưa vào URL, thứ tự sẽ thành:

http://USERNAME:PASSWORD@IP:PORT

Ví dụ:

import fetch from 'node-fetch';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl =
  'http://proxy-user:[email protected]:8080';

const agent = new HttpsProxyAgent(proxyUrl);

const response = await fetch('https://httpbin.org/ip', {
  agent
});

console.log(await response.json());

Xử lý ký tự đặc biệt trong thông tin đăng nhập

Nếu username hoặc password chứa @, :, /, # hay dấu cách, nối chuỗi trực tiếp có thể làm URL sai cấu trúc.

Hãy mã hóa từng giá trị bằng encodeURIComponent():

const username = encodeURIComponent(process.env.PROXY_USERNAME);
const password = encodeURIComponent(process.env.PROXY_PASSWORD);
const host = process.env.PROXY_HOST;
const port = process.env.PROXY_PORT;

const proxyUrl =
  `http://${username}:${password}@${host}:${port}`;

Cách khác an toàn hơn là dùng đối tượng URL:

const proxyUrl = new URL(
  `http://${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`
);

proxyUrl.username = process.env.PROXY_USERNAME;
proxyUrl.password = process.env.PROXY_PASSWORD;

const agent = new HttpsProxyAgent(proxyUrl);

Đối tượng URL tự xử lý phần mã hóa cần thiết và giúp đoạn mã dễ đọc hơn.

Không ghi mật khẩu proxy vào source code

Thông tin proxy không nên xuất hiện trực tiếp trong repository, ảnh chụp log hoặc thông báo lỗi.

Tạo tệp .env:

PROXY_HOST=103.10.20.30
PROXY_PORT=8080
PROXY_USERNAME=example-user
PROXY_PASSWORD=example-password

Thêm .env vào .gitignore, sau đó đọc cấu hình trong ứng dụng:

import 'dotenv/config';
import fetch from 'node-fetch';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl = new URL(
  `http://${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`
);

proxyUrl.username = process.env.PROXY_USERNAME;
proxyUrl.password = process.env.PROXY_PASSWORD;

const agent = new HttpsProxyAgent(proxyUrl);

const response = await fetch('https://httpbin.org/ip', {
  agent
});

console.log(await response.json());

Trên hệ thống production, nên dùng kho secret của nền tảng triển khai thay vì tệp .env nằm trên máy chủ.

Đặt timeout cho request

Request qua proxy có thể treo nếu proxy mất kết nối nhưng socket chưa đóng. Không đặt timeout sẽ khiến worker bị chiếm lâu và hàng đợi ngày càng lớn.

Có thể dùng AbortController:

import fetch from 'node-fetch';
import { HttpsProxyAgent } from 'https-proxy-agent';

async function fetchWithProxy(url, proxyUrl, timeout = 15000) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeout);

  try {
    const agent = new HttpsProxyAgent(proxyUrl);

    const response = await fetch(url, {
      agent,
      signal: controller.signal
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    return await response.json();
  } finally {
    clearTimeout(timer);
  }
}

Timeout nên dựa trên chất lượng mạng và thời gian phản hồi của website. Đặt quá thấp sẽ loại bỏ cả những request hợp lệ. Đặt quá cao làm hệ thống phản ứng chậm khi proxy lỗi.

Cách xoay proxy với node-fetch

Có hai cách xoay proxy thường gặp:

  1. Ứng dụng giữ một danh sách proxy và chọn proxy cho từng request.

  2. Nhà cung cấp sử dụng một gateway cố định nhưng thay IP ở phía máy chủ.

Cách thứ hai giúp code đơn giản hơn. Ứng dụng luôn kết nối đến cùng một host và port, còn việc đổi IP do hệ thống proxy xử lý.

Nếu tự quản lý danh sách, có thể dùng chiến lược round-robin.

Xoay proxy theo thứ tự

import fetch from 'node-fetch';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrls = [
  process.env.PROXY_URL_1,
  process.env.PROXY_URL_2,
  process.env.PROXY_URL_3
].filter(Boolean);

if (proxyUrls.length === 0) {
  throw new Error('Chưa cấu hình proxy');
}

const agents = proxyUrls.map(
  proxyUrl => new HttpsProxyAgent(proxyUrl)
);

let currentIndex = 0;

function getNextAgent() {
  const agent = agents[currentIndex];
  currentIndex = (currentIndex + 1) % agents.length;
  return agent;
}

async function request(url) {
  const response = await fetch(url, {
    agent: getNextAgent()
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  return response.json();
}

Round-robin giúp phân phối request tương đối đều. Tuy nhiên, chiến lược này chưa kiểm tra được proxy nào đang chậm hoặc đã mất kết nối.

Chọn proxy ngẫu nhiên

function getRandomAgent() {
  const index = Math.floor(Math.random() * agents.length);
  return agents[index];
}

Chọn ngẫu nhiên dễ triển khai nhưng không bảo đảm tải được chia đều trong một số lượng request nhỏ.

Nếu cần kiểm soát phiên, vùng IP hoặc thời gian đổi địa chỉ, hãy tham khảo cách hoạt động của rotating proxy.

Có nên tạo agent mới cho từng request?

Không nên tạo lại agent nếu nhiều request liên tiếp sử dụng cùng một proxy.

Tái sử dụng agent có thể tận dụng kết nối keep-alive, giảm thời gian bắt tay TCP và TLS. Một cách đơn giản là tạo trước agent cho từng proxy rồi lưu vào Map:

const agentCache = new Map();

function getAgent(proxyUrl) {
  if (!agentCache.has(proxyUrl)) {
    agentCache.set(
      proxyUrl,
      new HttpsProxyAgent(proxyUrl, {
        keepAlive: true
      })
    );
  }

  return agentCache.get(proxyUrl);
}

Nếu danh sách proxy thay đổi liên tục, cache cần giới hạn kích thước. Nếu không, ứng dụng có thể giữ quá nhiều socket và đối tượng agent trong bộ nhớ.

Gửi POST request qua proxy

Proxy agent không chỉ dùng cho GET. Bạn có thể gửi JSON, form data và các phương thức HTTP khác:

const response = await fetch('https://api.example.com/items', {
  method: 'POST',
  agent,
  headers: {
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Example item'
  })
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const result = await response.json();

Proxy thay đổi đường truyền của request. Nó không thay đổi quyền truy cập API. Token, cookie và dữ liệu gửi đi vẫn phải tuân thủ yêu cầu của website đích.

Cách dùng SOCKS5 proxy

HttpsProxyAgent không xử lý giao thức SOCKS. Với SOCKS4 hoặc SOCKS5, cài socks-proxy-agent:

npm install socks-proxy-agent

Cấu hình:

import fetch from 'node-fetch';
import { SocksProxyAgent } from 'socks-proxy-agent';

const proxyUrl =
  'socks5://username:password@proxy-host:port';

const agent = new SocksProxyAgent(proxyUrl);

const response = await fetch('https://httpbin.org/ip', {
  agent
});

console.log(await response.json());

Bạn có thể đọc thêm bài SOCKS Proxy là gì để phân biệt SOCKS5 với HTTP và HTTPS proxy.

Retry request thế nào cho đúng?

Không phải lỗi nào cũng nên thử lại.

Các lỗi kết nối, timeout, HTTP 408, 429 và một số lỗi 5xx có thể phù hợp để retry. Phần lớn lỗi 4xx cho thấy request có vấn đề và không tự hết khi gửi lại.

Một hàm retry nên có:

  • Số lần thử tối đa

  • Exponential backoff

  • Một khoảng ngẫu nhiên nhỏ

  • Timeout cho từng lần thử

  • Danh sách status được phép retry

  • Log không chứa mật khẩu proxy

Ví dụ:

const delay = ms =>
  new Promise(resolve => setTimeout(resolve, ms));

async function fetchWithRetry(url, options, maxAttempts = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      const response = await fetch(url, options);

      const canRetry =
        response.status === 408 ||
        response.status === 429 ||
        response.status >= 500;

      if (response.ok || !canRetry) {
        return response;
      }

      lastError = new Error(`HTTP ${response.status}`);
    } catch (error) {
      lastError = error;
    }

    if (attempt < maxAttempts) {
      const backoff = 500 * (2 ** (attempt - 1));
      const jitter = Math.floor(Math.random() * 250);
      await delay(backoff + jitter);
    }
  }

  throw lastError;
}

Nếu website trả về Retry-After, nên ưu tiên giá trị đó thay vì tự chọn thời gian chờ.

Retry quá nhanh có thể làm tình trạng giới hạn truy cập nặng hơn.

Các lỗi Node Fetch Proxy thường gặp

Lỗi 407 Proxy Authentication Required

Nguyên nhân thường gặp:

  • Sai username hoặc password

  • Tài khoản proxy đã hết hạn

  • Chưa whitelist IP máy chủ

  • Ký tự đặc biệt trong mật khẩu chưa được mã hóa

  • Dùng sai phương thức xác thực

Hãy kiểm tra proxy bằng một công cụ độc lập trước khi sửa code. Nếu proxy hoạt động ở nơi khác, kiểm tra lại URL và biến môi trường của ứng dụng.

Lỗi ECONNREFUSED

ECONNREFUSED cho biết kết nối đến host và port của proxy bị từ chối.

Cần kiểm tra:

  • Địa chỉ IP hoặc hostname

  • Port

  • Firewall

  • Proxy có đang hoạt động không

  • Máy chủ có được phép kết nối ra ngoài qua port đó không

Lỗi ETIMEDOUT

Proxy có thể quá chậm, mất kết nối hoặc không truy cập được website đích.

Không nên chỉ tăng timeout. Hãy ghi nhận thời gian phản hồi và tạm loại proxy liên tục vượt ngưỡng khỏi vòng xoay.

Lỗi ECONNRESET hoặc socket hang up

Kết nối bị đóng giữa chừng có thể đến từ proxy, website đích hoặc việc tái sử dụng socket.

Thử kiểm tra:

  • Tình trạng proxy

  • Phiên bản Node.js và package

  • Thiết lập keep-alive

  • Số request đồng thời

  • Timeout của proxy và website

  • Khả năng website đóng kết nối sớm

Lỗi chứng chỉ TLS

Không nên sửa lỗi TLS bằng cách đặt:

NODE_TLS_REJECT_UNAUTHORIZED=0

Thiết lập này tắt kiểm tra chứng chỉ cho toàn bộ process và làm mất lớp bảo vệ quan trọng.

Nếu proxy doanh nghiệp giải mã TLS bằng chứng chỉ riêng, hãy cài đúng CA hoặc cấu hình NODE_EXTRA_CA_CERTS. Chỉ sử dụng chứng chỉ do đơn vị quản trị mạng cung cấp và xác minh.

IP không thay đổi

Nếu request thành công nhưng IP vẫn là IP thật, nguyên nhân có thể là:

  • Agent không được truyền vào node-fetch

  • Đang dùng native fetch thay vì package node-fetch

  • URL kiểm tra IP bị cache

  • Proxy gateway đang giữ sticky session

  • Đoạn mã tạo agent nhưng request dùng một biến fetch khác

Hãy kiểm tra import và ghi log hostname của proxy, nhưng không ghi username hoặc password.

Cách chọn proxy cho node-fetch

Proxy datacenter phù hợp với API, kiểm thử và tác vụ cần tốc độ ổn định với chi phí hợp lý.

Proxy ISP phù hợp với phiên dài, cần địa chỉ IP ổn định và tín hiệu nhà mạng.

Proxy dân cư phù hợp với hoạt động kiểm tra nội dung theo vị trí hoặc thu thập dữ liệu công khai khi website cho phép. Bạn có thể xem thêm proxy dân cư là gì và tiêu chí lựa chọn.

Nếu cần lựa chọn loại IP và quốc gia, tham khảo trang mua proxy tại Proxify.

Checklist triển khai Node Fetch Proxy

Trước khi đưa ứng dụng lên production, hãy kiểm tra:

  1. Proxy đã được kiểm tra độc lập.

  2. Mật khẩu không nằm trong source code.

  3. Biến môi trường không xuất hiện trong log.

  4. Username và password được mã hóa đúng.

  5. Mỗi request có timeout.

  6. Retry chỉ áp dụng cho lỗi phù hợp.

  7. Agent được tái sử dụng khi dùng cùng proxy.

  8. Số kết nối đồng thời có giới hạn.

  9. Proxy lỗi được tạm loại khỏi vòng xoay.

  10. Hệ thống ghi lại latency và tỷ lệ thành công.

  11. Không tắt kiểm tra chứng chỉ TLS.

  12. Hoạt động thu thập dữ liệu tuân thủ điều khoản website.

Câu hỏi thường gặp

node-fetch có sẵn tùy chọn proxy không?

Không. Bạn cần tạo một proxy agent rồi truyền qua thuộc tính agent. Với proxy HTTP hoặc HTTPS, https-proxy-agent là lựa chọn phổ biến.

Có thể dùng cùng một agent cho nhiều request không?

Có. Tái sử dụng agent giúp tận dụng keep-alive và giảm chi phí tạo kết nối. Nếu đổi sang proxy khác, cần dùng agent tương ứng với proxy đó.

node-fetch có dùng được SOCKS5 không?

Có, nhưng cần socks-proxy-agent thay cho https-proxy-agent.

Vì sao cấu hình agent không hoạt động với native fetch?

Native fetch của Node.js dựa trên Undici và không sử dụng thuộc tính agent giống node-fetch. Bạn cần dùng dispatcher hoặc proxy agent của Undici.

Có nên đổi proxy sau mỗi request không?

Không phải lúc nào cũng cần. Luồng đăng nhập hoặc giao dịch nhiều bước thường cần giữ cùng một IP. Việc đổi IP nên dựa trên loại dữ liệu, giới hạn truy cập và yêu cầu giữ phiên.

Kết luận

Để dùng proxy với node-fetch, bạn cần tạo agent phù hợp rồi truyền agent đó vào từng request.

Cấu hình cơ bản chỉ mất vài dòng mã. Phần cần đầu tư nằm ở timeout, retry, bảo vệ thông tin đăng nhập, tái sử dụng kết nối và theo dõi chất lượng proxy.

Trước khi xử lý lỗi trong code, hãy kiểm tra proxy độc lập. Sau đó xác nhận ứng dụng đang dùng đúng node-fetch, đúng agent và đúng giao thức.

© 2026 Proxify.vn. All rights reserved.

Bảo mật · An toàn · Tự động