http proxy middleware
v3.0.3
Node.js proxying einfach gemacht. Konfigurieren Sie Proxy Middleware mühelos für Connect, Express, Next.js und viele weitere.
Angetrieben von der beliebten Nodejitsu http-proxy .
Diese Seite zeigt eine Dokumentation für Version V3.xx (Versionshinweise) an
Weitere Informationen zum Migrieren von V2.xx nach V3.xx finden Sie unter migration.md.
Wenn Sie nach älteren Dokumentation suchen. Gehen Sie zu:
Proxy /api -Anfragen an http://www.example.org
Tipp: Stellen Sie den Optionsteiler changeOrigin für namenbasierte virtuelle Hosted-Websites auf true ein.
// 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 Alle http-proxy Optionen können verwendet werden, zusammen mit einigen zusätzlichen http-proxy-middleware Optionen.
pathFilter (String, [] String, Glob, Globe, Funktion)pathRewrite (Objekt/Funktion)router (Objekt/Funktion)plugins (Array)ejectPlugins (boolean) Standard: false :logger (Objekt)http-proxy Ereignissehttp-proxy Optionennpm install --save-dev http-proxy-middleware Erstellen und konfigurieren Sie eine Proxy Middleware mit: 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.Optionen.Target : Ziel Host to Proxy to. (Protokoll + Host)
Optionen.Changeoriginin : Für virtuelle gehostete Websites
Die vollständige Liste der Konfigurationsoptionen http-proxy-middleware finden Sie
Ein Beispiel mit express Server.
// 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 ) ; Wenn Sie den app.use path des Servers verwenden möchten, um die Anforderungen zu entsprechen. Verwenden Sie die Option pathFilter , um Anfragen, die Sie für den Proxy möchten, weiter hinzuzufügen/auszuschließen.
app . use (
createProxyMiddleware ( {
target : 'http://www.example.org/api' ,
changeOrigin : true ,
pathFilter : '/api/proxy-only-this-path' ,
} ) ,
) ; app.use Dokumentation:
HTTP-Proxy-Middleware-Optionen:
pathFilter (String, [] String, Glob, Globe, Funktion) Begrenzen Sie, welche Anfragen ausgeweitet werden sollten. Der für die Filterung verwendete path ist die request.url . Url PathName. In Express ist dies der path relativ zum Mountspunkt des Proxy.
Pfad Matching
createProxyMiddleware({...}) - Übereinstimmt jedem Pfad, alle Anforderungen werden proxiert, wenn pathFilter nicht konfiguriert ist.createProxyMiddleware({ pathFilter: '/api', ...}) - stimmt Pfaden ab, beginnend mit /apiMultiple Pfadanpassungen
createProxyMiddleware({ pathFilter: ['/api', '/ajax', '/someotherpath'], ...})Wildcard -Pfad Matching
Für die feinkörnige Kontrolle können Sie Wildcard-Matching verwenden. Das Glob -Muster -Matching erfolgt durch Micromatch . Besuchen Sie Micromatch oder GLIB, um weitere Kugbing -Beispiele zu erhalten.
createProxyMiddleware({ pathFilter: '**', ...}) entspricht jedem Pfad, alle Anfragen werden vervollständigt.createProxyMiddleware({ pathFilter: '**/*.html', ...}) stimmt jedem Pfad überein, der mit .html endetcreateProxyMiddleware({ pathFilter: '/*.html', ...}) stimmt den Pfaden direkt unter Path-Absolute übereincreateProxyMiddleware({ pathFilter: '/api/**/*.html', ...}) stimmt mit Anfragen überein, die mit .html im Pfad von /api endencreateProxyMiddleware({ pathFilter: ['/api/**', '/ajax/**'], ...}) Kombinieren Sie mehrere MustercreateProxyMiddleware({ pathFilter: ['/api/**', '!**/bad.json'], ...}) AusschlussHinweis : Bei mehreren Pfadanpassungen können Sie keine String -Pfade und Wildcard -Pfade zusammen verwenden.
benutzerdefinierte Matching
Für die vollständige Kontrolle können Sie eine benutzerdefinierte Funktion bereitstellen, um zu bestimmen, welche Anfragen ausgewiesen werden sollten oder nicht.
/**
* @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 (Objekt/Funktion)Schreiben Sie das URL -Pfad des Ziels neu. Objektkeys werden als Regexp verwendet, um Pfade zu entsprechen.
// 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 (Objekt/Funktion) RE-Target option.target für bestimmte Anfragen.
// 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 (Array) 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) Standard: false : Wenn Sie mit den vorkonfigurierten Plugins nicht zufrieden sind, können Sie sie auswerfen, indem Sie ejectPlugins: true .
HINWEIS: Registrieren Sie Ihre eigenen Fehlerhandler, um zu verhindern, dass der Server abstürzt.
// 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 (Objekt) Konfigurieren Sie einen Protokoll, um Informationen von HTTP-Proxy-Middleware auszugeben: dh. console , winston , pino , bunyan , log4js usw.
Nur info , warn , error werden intern für die Kompatibilität für verschiedene Holzfäller verwendet.
Wenn Sie winston verwenden, aktivieren Sie die Interpolation: https://github.com/winstonjs/winston#string-interpolation
Weitere Informationen finden Sie unter Rezepten (Rezepte/logger.md) auch Logger -Rezepte.
createProxyMiddleware ( {
logger : console ,
} ) ; http-proxy Ereignisse Abonnieren Sie HTTP-Proxy-Ereignisse mit der on Option:
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 : Funktion, abonnieren Sie das error von HTTP-Proxy für die benutzerdefinierte Fehlerbehandlung.
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 : Funktion, abonnieren Sie das proxyRes von 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 : Funktion, abonnieren Sie das proxyReq Ereignis von HTTP-Proxy.
function onProxyReq ( proxyReq , req , res ) {
// add custom header to request
proxyReq . setHeader ( 'x-added' , 'foobar' ) ;
// or log the req
} option.on.proxyreqws : Funktion, abonnieren Sie das proxyReqWs Ereignis von Http-Proxy.
function onProxyReqWs ( proxyReq , req , socket , options , head ) {
// add custom header
proxyReq . setHeader ( 'X-Special-Proxy-Header' , 'foobar' ) ;
} option.on.open : Funktion, abonnieren Sie das open Ereignis von HTTP-Proxy.
function onOpen ( proxySocket ) {
// listen for messages coming FROM the target here
proxySocket . on ( 'data' , hybridParseAndLogMessage ) ;
} option.on.close : Funktion, abonnieren Sie das close Ereignis von HTTP-Proxy.
function onClose ( res , socket , head ) {
// view disconnected websocket connections
console . log ( 'Client disconnected' ) ;
} http-proxy OptionenDie folgenden Optionen werden in der zugrunde liegenden HTTP-Proxy-Bibliothek bereitgestellt.
Option.Target : URL -Zeichenfolge, die mit dem URL -Modul analysiert werden soll
Option.forward : URL -Zeichenfolge, die mit dem URL -Modul analysiert werden soll
Option.Agent : Objekt, das an HTTP (en) übergeben werden soll (siehe HTTPS -Agenten des Knotens und HTTP -Agenten)
Option.SSL : Objekt, das an https.createServer () übergeben werden soll
Option.WS : TRUE/FALSCH: Wenn Sie Proxy Websockets möchten
option.xfwd : true/false, fügt X-Forward-Header hinzu
Option.Secure : True/False, wenn Sie die SSL -Zertifikate überprüfen möchten
Option.toproxy : true/false, über die absolute URL als path (nützlich für Stellvertreter zu Proxies))
option.prependPath : true/false, Standard: TRUE - Geben Sie an, ob Sie den Pfad des Ziels zum Proxy -Pfad vorbereiten möchten
option.ignorePath : true / false, Standard: Falsch - Geben Sie an, ob Sie den Proxypfad der eingehenden Anfrage ignorieren möchten (Hinweis: Sie müssen bei Bedarf manuell anhängen).
Option.localaddress : Lokale Schnittstellenzeichenfolge für ausgehende Verbindungen zu binden
Option.Changeoriginin : True/False, Standard: Falsch - ändert den Ursprung des Host -Headers in die Ziel -URL
Option.PreserveheaderKeyCase : TRUE/FALSCH, Standard: Falsch - Geben Sie an, ob Sie einen Buchstabenfall der Antwort -Header -Taste beibehalten möchten
Option.AUTH : Basic Authentication IE 'Benutzer: Passwort', um einen Autorisierungsheader zu berechnen.
Option.HOSTREWRITE : Schreiben Sie den Standort -Hostname unter (301/302/307/308) um.
Option.AutoreWrite : Schreiben Sie den Standort Host/Port auf (301/302/307/308) um, die auf dem angeforderten Host/Port basierten. Standard: Falsch.
Option.Protocolrewrite : Umleitet das Standortprotokoll auf (301/302/307/308) auf 'http' oder 'https' um. Standard: null.
option.cookiedomainrewrite : Schreiben Sie die Domäne von set-cookie -Headern neu. Mögliche Werte:
false (Standard): Deaktivieren Sie das Cookie -Umschreiben
String: Neue Domäne, zum Beispiel cookieDomainRewrite: "new.domain" . Um die Domäne zu entfernen, verwenden Sie cookieDomainRewrite: "" .
Objekt: Zuordnung von Domänen auf neue Domänen, verwenden Sie "*" um alle Domänen zu entsprechen.
Halten Sie beispielsweise eine Domäne unverändert, schreiben Sie eine Domäne neu und entfernen Sie andere Domänen:
cookieDomainRewrite: {
"unchanged.domain" : " unchanged.domain " ,
"old.domain" : " new.domain " ,
"*" : " "
} option.cookiepathewrite : Schreiben Sie den Pfad der set-cookie -Header neu. Mögliche Werte:
false (Standard): Deaktivieren Sie das Cookie -Umschreiben
String: neuer Pfad, zum Beispiel cookiePathRewrite: "/newPath/" . Um den Weg zu entfernen, verwenden Sie cookiePathRewrite: "" . Um den Pfad zu setzen, um Root zu verwenden, verwenden Sie cookiePathRewrite: "/" .
Objekt: Zuordnung von Pfaden auf neue Pfade, verwenden Sie "*" , um alle Pfade zu entsprechen. Um einen Pfad unverändert zu halten, schreiben Sie einen Pfad neu und entfernen Sie andere Pfade:
cookiePathRewrite: {
"/unchanged.path/" : " /unchanged.path/ " ,
"/old.path/" : " /new.path/ " ,
"*" : " "
} Option.Headers : Objekt, fügt Anforderungsheader hinzu. (Beispiel: {host:'www.example.org'} )
Option.ProxyTimeOut : Timeout (in Millis) Wenn der Proxy keine Antwort von Target erhält
Option.Timeout : Timeout (in Millis) für eingehende Anfragen
option.Followredirects : true/false, Standard: Falsch - Geben Sie an, ob Sie Ausleitungen befolgen möchten
Option.selfHandLesponse true/false, wenn auf true festgelegt, wird keiner der Weboutgoing -Pässe aufgerufen und es liegt in Ihrer Verantwortung, die Antwort angemessen zurückzugeben, indem Sie das proxyRes zuhören und wirken
Option.Buffer : Datenstrom, die als Anforderungsgremium gesendet werden sollen. Möglicherweise haben Sie eine Middleware, die den Anforderungsstrom konsumiert, bevor Sie ihn auf z.
'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 } ) ; In den vorherigen Beispielen von WebSocket stützt sich HTTP-Proxy-Middleware auf eine erste HTTP-Anforderung, um das HTTP upgrade Ereignis anzuhören. Wenn Sie Proxy WebSockets ohne die erste HTTP -Anfrage für die HTTP upgrade -Veranstaltung des Servers manuell abonnieren müssen.
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' Intercept -Anforderungen von Downstream durch Definieren von onProxyReq in createProxyMiddleware .
Derzeit ist der einzige vorgestellte Anfrage-Interceptor fixRequestBody , mit dem Proxied-Post-Anfragen festgelegt werden, wenn bodyParser vor dieser Middleware angewendet wird.
Beispiel:
const { createProxyMiddleware , fixRequestBody } = require ( 'http-proxy-middleware' ) ;
const proxy = createProxyMiddleware ( {
/**
* Fix bodyParser
**/
on : {
proxyReq : fixRequestBody ,
} ,
} ) ; Abfangenreaktionen aus stromaufwärts mit responseInterceptor . (Stellen Sie sicher, dass Sie selfHandleResponse: true )
Antworten, die mit brotli , gzip und deflate komprimiert werden, werden automatisch dekomprimiert. Die Antwort wird als buffer (DOCS) zurückgegeben, den Sie manipulieren können.
Bei buffer ist die Antwortmanipulation nicht auf Textantworten (HTML/CSS/JS usw.) beschränkt; Bildmanipulation ist ebenfalls möglich. (Beispiel)
HINWEIS: responseInterceptor deaktiviert das Streaming der Antwort von Target.
Beispiel:
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
} ) ,
} ,
} ) ;Weitere Beispiele finden Sie unter Abhörrezepte.
Node.js 17+ bevorzugt IPv4 nicht mehr gegenüber IPv6 für DNS -Suchdaten. ZB ist es nicht garantiert, dass localhost auf 127.0.0.1 gelöst wird - es könnte genauso gut ::1 (oder eine andere IP -Adresse) sein.
Wenn Ihr Zielserver nur IPv4 -Verbindungen akzeptiert, fehlschlägt der Versuch, Proxy zu localhost zu profitieren, fehl, wenn es auf ::1 (IPv6) aufgelöst wird.
Möglichkeiten, es zu lösen:
target: "http://localhost" zu target: "http://127.0.0.1" (IPv4).node ausgeführt wird: node index.js --dns-result-order=ipv4first . (Nicht empfohlen.)Hinweis: Es gibt eine Sache, die als glückliche Augäpfel bezeichnet wird, was bedeutet, dass sie parallel mit IPv4 und IPv6 eine Verbindung herstellen müssen, die Node.js nicht hat, erklärt jedoch, warum
curlbeispielsweise eine Verbindung herstellen kann.
Konfigurieren Sie die DEBUG -Umgebungsvariable Aktivieren Sie die Debug -Protokollierung.
Weitere Optionen finden Sie unter debug -Projekt.
DEBUG=http-proxy-middleware * node server.js
$ http-proxy-middleware proxy created +0ms
$ http-proxy-middleware proxying request to target: ' http://www.example.org ' +359msZeigen und spielen Sie mit Arbeitsbeispielen herum.
Sehen Sie sich die Rezepte für gemeinsame Anwendungsfälle an.
http-proxy-middleware ist mit den folgenden Servern kompatibel:
Beispielimplementierungen finden Sie in den Serverrezepten.
Führen Sie die Testsuite aus:
# 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 spellcheckDie MIT -Lizenz (MIT)
Copyright (C) 2015-2024 Steven Chim
