http proxy middleware
v3.0.3
Node.js proxying simplificou. Configure o middleware proxy com facilidade para conectar, exprestar, o próximo.js e muito mais.
Alimentado pelo popular nodejitsu http-proxy .
Esta página está mostrando documentação para a versão v3.xx (notas de versão)
Consulte Migration.md para obter detalhes sobre como migrar de v2.xx para v3.xx
Se você está procurando documentação mais antiga. Vá para:
Solicitações de proxy /api para http://www.example.org
Dica: defina a opção changeOrigin como true para sites virtuais baseados em nomes.
// typescript
import * as express from 'express' ;
import type { Request , Response , NextFunction } from 'express' ;
import { createProxyMiddleware } from 'http-proxy-middleware' ;
import type { Filter , Options , RequestHandler } from 'http-proxy-middleware' ;
const app = express ( ) ;
const proxyMiddleware = createProxyMiddleware < Request , Response > ( {
target : 'http://www.example.org/api' ,
changeOrigin : true ,
} ) ;
app . use ( '/api' , proxyMiddleware ) ;
app . listen ( 3000 ) ;
// proxy and keep the same base path "/api"
// http://127.0.0.1:3000/api/foo/bar -> http://www.example.org/api/foo/bar Todas as opções http-proxy podem ser usadas, juntamente com algumas opções extras http-proxy-middleware .
pathFilter (String, [] String, Glob, [] glob, função)pathRewrite (objeto/função)router (objeto/função)plugins (matriz)ejectPlugins (boolean) Padrão: falselogger (objeto)http-proxyhttp-proxynpm install --save-dev http-proxy-middleware Crie e configure um middleware proxy com: createProxyMiddleware(config) .
const { createProxyMiddleware } = require ( 'http-proxy-middleware' ) ;
const apiProxy = createProxyMiddleware ( {
target : 'http://www.example.org' ,
changeOrigin : true ,
} ) ;
// 'apiProxy' is now ready to be used as middleware in a server.options.Target : alvo host para proxy para. (protocolo + host)
Options.ChangeOrigin : para sites hospedados virtuais
Consulte Lista completa de opções de configuração http-proxy-middleware
Um exemplo com servidor express .
// include dependencies
const express = require ( 'express' ) ;
const { createProxyMiddleware } = require ( 'http-proxy-middleware' ) ;
const app = express ( ) ;
// create the proxy
/** @type {import('http-proxy-middleware/dist/types').RequestHandler<express.Request, express.Response>} */
const exampleProxy = createProxyMiddleware ( {
target : 'http://www.example.org/api' , // target host with the same base path
changeOrigin : true , // needed for virtual hosted sites
} ) ;
// mount `exampleProxy` in web server
app . use ( '/api' , exampleProxy ) ;
app . listen ( 3000 ) ; Se você deseja usar o parâmetro path app.use servidor. Use a opção pathFilter para incluir/excluir solicitações que você deseja proxy.
app . use (
createProxyMiddleware ( {
target : 'http://www.example.org/api' ,
changeOrigin : true ,
pathFilter : '/api/proxy-only-this-path' ,
} ) ,
) ; app.use Documentação:
Opções HTTP-Proxy-Middleware:
pathFilter (String, [] String, Glob, [] glob, função) Restringir quais solicitações devem ser proxiadas. O path usado para filtragem é a request.url Pathname. Em Express, este é o path em relação ao ponto de montagem do proxy.
correspondência de caminho
createProxyMiddleware({...}) - corresponde a qualquer caminho, todas as solicitações serão proxiadas quando pathFilter não estiver configurado.createProxyMiddleware({ pathFilter: '/api', ...}) - corresponde aos caminhos que começam com /apicorrespondência múltipla de caminho
createProxyMiddleware({ pathFilter: ['/api', '/ajax', '/someotherpath'], ...})Caminho curinga correspondente
Para controle de granulação fina, você pode usar a correspondência curinga. A correspondência de padrões glob é feita por micromatch . Visite Micromatch ou Glob para obter mais exemplos de globs.
createProxyMiddleware({ pathFilter: '**', ...}) corresponde a qualquer caminho, todas as solicitações serão proxiadas.createProxyMiddleware({ pathFilter: '**/*.html', ...}) corresponde a qualquer caminho que termine com .htmlcreateProxyMiddleware({ pathFilter: '/*.html', ...}) corresponde aos caminhos diretamente sob o caminho do path-absolutecreateProxyMiddleware({ pathFilter: '/api/**/*.html', ...}) corresponde às solicitações que terminam com .html no caminho de /apicreateProxyMiddleware({ pathFilter: ['/api/**', '/ajax/**'], ...}) Combine vários padrõescreateProxyMiddleware({ pathFilter: ['/api/**', '!**/bad.json'], ...}) exclusãoNOTA : Na correspondência de vários caminhos, você não pode usar caminhos de cordas e caminhos curinga juntos.
correspondência personalizada
Para controle total, você pode fornecer uma função personalizada para determinar quais solicitações devem ser procuradas ou não.
/**
* @return {Boolean}
*/
const pathFilter = function ( path , req ) {
return path . match ( '^/api' ) && req . method === 'GET' ;
} ;
const apiProxy = createProxyMiddleware ( {
target : 'http://www.example.org' ,
pathFilter : pathFilter ,
} ) ;pathRewrite (objeto/função)Reescrever o caminho da URL do Target. As teclas de objetos serão usadas como regexp para corresponder aos caminhos.
// rewrite path
pathRewrite: { '^/old/api' : '/new/api' }
// remove path
pathRewrite: { '^/remove/api' : '' }
// add base path
pathRewrite: { '^/' : '/basepath/' }
// custom rewriting
pathRewrite: function ( path , req ) { return path . replace ( '/api' , '/base/api' ) }
// custom rewriting, returning Promise
pathRewrite: async function ( path , req ) {
const should_add_something = await httpRequestToDecideSomething ( path ) ;
if ( should_add_something ) path += "something" ;
return path ;
}router (objeto/função) Re-alvo option.target para solicitações específicas.
// Use `host` and/or `path` to match requests. First match will be used.
// The order of the configuration matters.
router: {
'integration.localhost:3000' : 'http://127.0.0.1:8001' , // host only
'staging.localhost:3000' : 'http://127.0.0.1:8002' , // host only
'localhost:3000/api' : 'http://127.0.0.1:8003' , // host + path
'/rest' : 'http://127.0.0.1:8004' // path only
}
// Custom router function (string target)
router: function ( req ) {
return 'http://127.0.0.1:8004' ;
}
// Custom router function (target object)
router: function ( req ) {
return {
protocol : 'https:' , // The : is required
host : '127.0.0.1' ,
port : 8004
} ;
}
// Asynchronous router function which returns promise
router: async function ( req ) {
const url = await doSomeIO ( ) ;
return url ;
}plugins (matriz) const simpleRequestLogger = ( proxyServer , options ) => {
proxyServer . on ( 'proxyReq' , ( proxyReq , req , res ) => {
console . log ( `[HPM] [ ${ req . method } ] ${ req . url } ` ) ; // outputs: [HPM] GET /users
} ) ;
} ,
const config = {
target : `http://example.org` ,
changeOrigin : true ,
plugins : [ simpleRequestLogger ] ,
} ;ejectPlugins (boolean) Padrão: false Se você não estiver satisfeito com os plug-ins pré-configurados, pode ejetá-los configurando ejectPlugins: true .
Nota: Registre seus próprios manipuladores de erro para impedir que o servidor trave.
// eject default plugins and manually add them back
const {
debugProxyErrorsPlugin , // subscribe to proxy errors to prevent server from crashing
loggerPlugin , // log proxy events to a logger (ie. console)
errorResponsePlugin , // return 5xx response on proxy error
proxyEventsPlugin , // implements the "on:" option
} = require ( 'http-proxy-middleware' ) ;
createProxyMiddleware ( {
target : `http://example.org` ,
changeOrigin : true ,
ejectPlugins : true ,
plugins : [ debugProxyErrorsPlugin , loggerPlugin , errorResponsePlugin , proxyEventsPlugin ] ,
} ) ;logger (objeto) Configure um logger para produzir informações de http-proxy-middleware: ie. console , winston , pino , bunyan , log4js , etc ...
Somente info , warn , error são usadas internamente para compatibilidade em diferentes madeireiros.
Se você usar winston , certifique-se de ativar a interpolação: https://github.com/winstonjs/winston#string-interpolation
Consulte também Receitas de Logger (Receitas/Logger.md) para obter mais detalhes.
createProxyMiddleware ( {
logger : console ,
} ) ; http-proxy Inscreva-se nos eventos HTTP-Proxy com a opção on :
createProxyMiddleware ( {
target : 'http://www.example.org' ,
on : {
proxyReq : ( proxyReq , req , res ) => {
/* handle proxyReq */
} ,
proxyRes : ( proxyRes , req , res ) => {
/* handle proxyRes */
} ,
error : ( err , req , res ) => {
/* handle error */
} ,
} ,
} ) ; option.on.error : função, assine o evento error do http-proxy para manipulação de erros personalizada.
function onError ( err , req , res , target ) {
res . writeHead ( 500 , {
'Content-Type' : 'text/plain' ,
} ) ;
res . end ( 'Something went wrong. And we are reporting a custom error message.' ) ;
} Option.On.Proxyres : Função, assine o evento proxyRes do http-proxy.
function onProxyRes ( proxyRes , req , res ) {
proxyRes . headers [ 'x-added' ] = 'foobar' ; // add new header to response
delete proxyRes . headers [ 'x-removed' ] ; // remove header from response
} option.on.proxyreq : função, assine o evento proxyReq da http-proxy.
function onProxyReq ( proxyReq , req , res ) {
// add custom header to request
proxyReq . setHeader ( 'x-added' , 'foobar' ) ;
// or log the req
} Option.On.ProxyreqWs : Função, assine o evento proxyReqWs da http-proxy.
function onProxyReqWs ( proxyReq , req , socket , options , head ) {
// add custom header
proxyReq . setHeader ( 'X-Special-Proxy-Header' , 'foobar' ) ;
} option.on.open : função, assine o evento open do http-proxy.
function onOpen ( proxySocket ) {
// listen for messages coming FROM the target here
proxySocket . on ( 'data' , hybridParseAndLogMessage ) ;
} option.on.close : função, assine o evento close do http-proxy.
function onClose ( res , socket , head ) {
// view disconnected websocket connections
console . log ( 'Client disconnected' ) ;
} http-proxyAs seguintes opções são fornecidas pela Biblioteca HTTP-Proxy subjacente.
Option.Target : URL String a ser analisada com o módulo URL
Option.forward : URL String a ser analisada com o módulo URL
Option.Agent : Objeto a ser passado para HTTP (S) .request (consulte Objetos de agente HTTPS e HTTP do Node)
Option.SSL : Objeto a ser passado para https.createServer ()
option.ws : true/false: se você deseja proxy websockets
option.xfwd : true/false, adiciona cabeçalhos X-Forward
Option.Secure : True/False, se você deseja verificar os certificados SSL
Option.toProxy : true/false, passa o URL absoluto como o path (útil para proxy para proxies)
Option.PrependPath : true/false, padrão: true - especifique se você deseja prender o caminho do alvo ao caminho do proxy
Option.ignorePath : true / false, padrão: false - especifique se você deseja ignorar o caminho de proxy da solicitação de entrada (Nota: você precisará anexar / manualmente, se necessário).
option.localaddress : string de interface local para ligar para conexões de saída
Option.Changeorigin : true/false, padrão: false - altera a origem do cabeçalho do host para o URL de destino
Option.PreserveHeaderKeyCase : True/False, Padrão: Falso - Especifique se você deseja manter a chave do cabeçalho do caso da letra de resposta
Option.Auth : Autenticação básica IE 'Usuário: senha' para calcular um cabeçalho de autorização.
Option.HoStrewrite : Reescreva o nome do Host Location em (301/302/307/308) redireciona.
Option.AutoreWrite : Reescreva o host/porta Location On (301/302/307/308) redireciona com base no host/porta solicitado. Padrão: false.
Option.protocolrewrite : Reescreva o protocolo de localização no (301/302/307/308) redireciona para 'http' ou 'https'. Padrão: NULL.
Option.cookiedomAinrewrite : reescreva o domínio dos cabeçalhos set-cookie . Valores possíveis:
false (padrão): desativar a reescrita de cookies
String: Novo domínio, por exemplo cookieDomainRewrite: "new.domain" . Para remover o domínio, use cookieDomainRewrite: "" .
Objeto: Mapeamento de domínios para novos domínios, use "*" para corresponder a todos os domínios.
Por exemplo, mantenha um domínio inalterado, reescreva um domínio e remova outros domínios:
cookieDomainRewrite: {
"unchanged.domain" : " unchanged.domain " ,
"old.domain" : " new.domain " ,
"*" : " "
} Option.CookiePathRite : Reescreva o caminho dos cabeçalhos set-cookie . Valores possíveis:
false (padrão): desativar a reescrita de cookies
String: novo caminho, por exemplo cookiePathRewrite: "/newPath/" . Para remover o caminho, use cookiePathRewrite: "" . Para definir o caminho para a raiz, use cookiePathRewrite: "/" .
Objeto: Mapeamento de caminhos para novos caminhos, use "*" para corresponder a todos os caminhos. Por exemplo, para manter um caminho inalterado, reescrever um caminho e remover outros caminhos:
cookiePathRewrite: {
"/unchanged.path/" : " /unchanged.path/ " ,
"/old.path/" : " /new.path/ " ,
"*" : " "
} Option.Headers : Objeto, adiciona cabeçalhos de solicitação. (Exemplo: {host:'www.example.org'} )
Option.ProxyTimeout : Timeout (em Millis) quando o Proxy não recebe resposta do Target
Option.Timeout : Timeout (em Millis) para solicitações de entrada
option.followDredirects : true/false, padrão: false - especifique se você deseja seguir os redirecionamentos
Option.SelfHandleSponse True/False, se definido como True, nenhum dos passes da Web Outroting é chamado e é sua responsabilidade devolver adequadamente a resposta ouvindo e agindo no evento proxyRes
Option.Buffer : fluxo de dados a serem enviados como o corpo de solicitação. Talvez você tenha algum middleware que consome o fluxo de solicitações antes de proxi -lo em por exemplo, se você ler o corpo de uma solicitação em um campo chamado 'req.rawbody', você pode conter esse campo na opção Buffer:
'use strict' ;
const streamify = require ( 'stream-array' ) ;
const HttpProxy = require ( 'http-proxy' ) ;
const proxy = new HttpProxy ( ) ;
module . exports = ( req , res , next ) => {
proxy . web (
req ,
res ,
{
target : 'http://127.0.0.1:4003/' ,
buffer : streamify ( req . rawBody ) ,
} ,
next ,
) ;
} ; // verbose api
createProxyMiddleware ( { pathFilter : '/' , target : 'http://echo.websocket.org' , ws : true } ) ; Nos exemplos anteriores do WebSocket, o HTTP-Proxy-Middleware conta com uma solicitação inicial HTTP para ouvir o evento upgrade HTTP. Se você precisar proxy WebSockets sem a solicitação inicial HTTP, poderá assinar o evento upgrade HTTP do servidor manualmente.
const wsProxy = createProxyMiddleware ( { target : 'ws://echo.websocket.org' , changeOrigin : true } ) ;
const app = express ( ) ;
app . use ( wsProxy ) ;
const server = app . listen ( 3000 ) ;
server . on ( 'upgrade' , wsProxy . upgrade ) ; // <-- subscribe to http 'upgrade' Interceptar solicitações do downstream Definindo onProxyReq no createProxyMiddleware .
Atualmente, o único interceptador de solicitação pré-fornecido é fixRequestBody , que é usado para corrigir solicitações de postagem proxiadas quando bodyParser é aplicado antes deste middleware.
Exemplo:
const { createProxyMiddleware , fixRequestBody } = require ( 'http-proxy-middleware' ) ;
const proxy = createProxyMiddleware ( {
/**
* Fix bodyParser
**/
on : {
proxyReq : fixRequestBody ,
} ,
} ) ; Interceptar respostas do upstream com responseInterceptor . (Certifique -se de definir selfHandleResponse: true )
As respostas que são compactadas com brotli , gzip e deflate serão descomprimidas automaticamente. A resposta será devolvida como buffer (documentos) que você pode manipular.
Com buffer , a manipulação da resposta não se limita às respostas de texto (HTML/CSS/JS, etc ...); A manipulação da imagem também será possível. (exemplo)
NOTA: responseInterceptor Desativa o streaming da resposta do Target.
Exemplo:
const { createProxyMiddleware , responseInterceptor } = require ( 'http-proxy-middleware' ) ;
const proxy = createProxyMiddleware ( {
/**
* IMPORTANT: avoid res.end being called automatically
**/
selfHandleResponse : true , // res.end() will be called internally by responseInterceptor()
/**
* Intercept response and replace 'Hello' with 'Goodbye'
**/
on : {
proxyRes : responseInterceptor ( async ( responseBuffer , proxyRes , req , res ) => {
const response = responseBuffer . toString ( 'utf8' ) ; // convert buffer to string
return response . replace ( 'Hello' , 'Goodbye' ) ; // manipulate response and return the result
} ) ,
} ,
} ) ;Confira as receitas de interceptação para obter mais exemplos.
O Node.js 17+ não prefere mais IPv4 sobre IPv6 para pesquisas DNS. Por exemplo, não é garantido que localhost será resolvido para 127.0.0.1 - pode ser melhor ser ::1 (ou algum outro endereço IP).
Se o seu servidor de destino aceitar apenas as conexões IPv4, tentar proxy para localhost falhará se for resolvido ::1 (IPv6).
Maneiras de resolvê -lo:
target: "http://localhost" para target: "http://127.0.0.1" (IPv4).node : node index.js --dns-result-order=ipv4first . (Não recomendado.)Nota: Há uma coisa chamada Happy Eyeballs, que significa se conectar ao IPv4 e IPv6 em paralelo, que o Node.js não possui, mas explica por que, por exemplo,
curlpode se conectar.
Configure a variável de ambiente de DEBUG Ativar o log de depuração.
Consulte o projeto debug para obter mais opções.
DEBUG=http-proxy-middleware * node server.js
$ http-proxy-middleware proxy created +0ms
$ http-proxy-middleware proxying request to target: ' http://www.example.org ' +359msVer e brincar com exemplos de trabalho.
Veja as receitas para casos de uso comuns.
http-proxy-middleware é compatível com os seguintes servidores:
As implementações de amostra podem ser encontradas nas receitas do servidor.
Execute a suíte de teste:
# install dependencies
$ yarn
# linting
$ yarn lint
$ yarn lint:fix
# building (compile typescript to js)
$ yarn build
# unit tests
$ yarn test
# code coverage
$ yarn cover
# check spelling mistakes
$ yarn spellcheckA licença do MIT (MIT)
Copyright (c) 2015-2024 Steven Chim
