http proxy middleware
v3.0.3
node.jsプロキシは簡単になりました。コネクト、エクスプレス、next.jsなどのために簡単にプロキシミドルウェアを構成します。
人気のNodejitsuhttp http-proxyを搭載しています。
このページは、バージョンv3.xx（リリースノート）のドキュメントを示しています
v2.xxからv3.xxに移行する方法の詳細については、migration.mdを参照してください
古いドキュメントを探している場合。移動：
プロキシ/apiはhttp://www.example.orgにリクエストします
ヒント：名前ベースの仮想ホストサイトのオプションchangeOriginをtrueに設定します。
// 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すべてのhttp-proxyオプションを使用することができ、いくつかの追加のhttp-proxy-middlewareオプションを使用できます。
pathFilter （string、[] string、glob、[] glob、function）pathRewrite （オブジェクト/関数）router （オブジェクト/関数）plugins （配列）ejectPlugins （boolean）デフォルト： falselogger （オブジェクト）http-proxyイベントhttp-proxyオプションnpm install --save-dev http-proxy-middlewareプロキシミドルウェアを作成して構成します： 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 ：プロキシのターゲットホスト。 （プロトコル +ホスト）
options.changeorigin ：仮想ホストサイト用
http-proxy-middleware構成オプションの完全なリストを参照してください
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 ) ;サーバーのapp.use pathパラメーターを使用してリクエストを一致させる場合。 pathFilterオプションを使用して、プロキシを使用するリクエストを追加/除外します。
app . use (
createProxyMiddleware ( {
target : 'http://www.example.org/api' ,
changeOrigin : true ,
pathFilter : '/api/proxy-only-this-path' ,
} ) ,
) ; app.useドキュメント：
http-proxy-middlewareオプション：
pathFilter （string、[] string、glob、[] glob、function）どのリクエストをプロキシにするか絞り込みます。フィルタリングに使用されるpath 、 request.url pathnameです。 Expressでは、これはプロキシのマウントポイントに対するpathです。
パスマッチング
createProxyMiddleware({...}) - 任意のパスを一致させます。すべてのリクエストは、 pathFilterが構成されていないときにプロキシになります。createProxyMiddleware({ pathFilter: '/api', ...}) - /apiから始まるパスを一致させる複数のパスマッチング
createProxyMiddleware({ pathFilter: ['/api', '/ajax', '/someotherpath'], ...})ワイルドカードパスマッチング
細粒コントロールの場合、ワイルドカードマッチングを使用できます。 GLOBパターンマッチングはMicroMatchによって行われます。より多くのグローブの例については、MicroMatchまたはGlobにアクセスしてください。
createProxyMiddleware({ pathFilter: '**', ...})任意のパスと一致し、すべてのリクエストがプロキシになります。createProxyMiddleware({ pathFilter: '**/*.html', ...}) .htmlで終わるパスと一致するcreateProxyMiddleware({ pathFilter: '/*.html', ...})パスアブソルートの直接のパスを一致させますcreateProxyMiddleware({ pathFilter: '/api/**/*.html', ...}) /apiのパスで.htmlで終了するリクエストに一致しますcreateProxyMiddleware({ pathFilter: ['/api/**', '/ajax/**'], ...})複数のパターンを組み合わせますcreateProxyMiddleware({ pathFilter: ['/api/**', '!**/bad.json'], ...})除外注：複数のパスマッチングでは、文字列パスとワイルドカードパスを一緒に使用することはできません。
カスタムマッチング
完全に制御するには、カスタム関数を提供して、どのリクエストをプロキシまたはノットにするかを判断できます。
/**
* @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 （オブジェクト/関数）ターゲットのURLパスを書き直します。 Object-Keysは、パスを一致させるためにRegexpとして使用されます。
// 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 （オブジェクト/関数）特定のリクエスト用のターゲットoption.target 。ターゲット。
// 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 （配列） 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）デフォルト： false事前に構成されたプラグインに満足していない場合は、 ejectPlugins: trueを構成することでそれらを排出できます。
注：サーバーがクラッシュするのを防ぐために、独自のエラーハンドラーを登録します。
// 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 （オブジェクト） http-proxy-middlewareから情報を出力するためにロガーを構成します：ie。 console 、 winston 、 pino 、 bunyan 、 log4jsなど...
info 、 warn 、 errorのみが、さまざまなロガー間の互換性に内部的に使用されます。
winstonを使用する場合は、補間を有効にしてください：https：//github.com/winstonjs/winston#string-interpolation
詳細については、Logger Recipes（Recipes/Logger.md）も参照してください。
createProxyMiddleware ( {
logger : console ,
} ) ; http-proxyイベントonオプションを使用して、http-proxyイベントを購読してください。
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 ：関数、カスタムエラー処理のためにHTTP-Proxyのerrorイベントを購読します。
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 ：function、http-proxyのproxyResイベントに登録します。
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 ：function、http-proxyのproxyReqイベントを購読します。
function onProxyReq ( proxyReq , req , res ) {
// add custom header to request
proxyReq . setHeader ( 'x-added' , 'foobar' ) ;
// or log the req
} option.on.proxyreqws ：function、http-proxyのproxyReqWsイベントを購読します。
function onProxyReqWs ( proxyReq , req , socket , options , head ) {
// add custom header
proxyReq . setHeader ( 'X-Special-Proxy-Header' , 'foobar' ) ;
} option.on.Open：function、http-proxyのopenイベントを購読します。
function onOpen ( proxySocket ) {
// listen for messages coming FROM the target here
proxySocket . on ( 'data' , hybridParseAndLogMessage ) ;
} option.on.close ：function、http-proxyのcloseイベントを購読します。
function onClose ( res , socket , head ) {
// view disconnected websocket connections
console . log ( 'Client disconnected' ) ;
} http-proxyオプション次のオプションは、基礎となるHTTP-Proxyライブラリによって提供されます。
option.Target：URLモジュールに解析されるURL文字列
Option.Forward ：URLモジュールで解析されるURL文字列
option.agent ：http（s）に渡されるオブジェクト.request（ノードのHTTPSエージェントとHTTPエージェントオブジェクトを参照）
option.ssl ：https.createserver（）に渡されるオブジェクト
option.ws：true/false：websocketsをプロキシする場合
option.xfwd ：true/false、X-Forwardヘッダーを追加します
option.secure：ssl certsを確認する場合は、true/false
option.toproxy ：true/false、絶対URLをpathとして渡します（プロキシへのプロキシングに役立ちます）
option.predentpath ：true/false、default：true-ターゲットのパスをプロキシパスへのパスを準備するかどうかを指定します
option.ignorepath ：true / false、default：false-着信リクエストのプロキシパスを無視するかどうかを指定します（注：必要に応じて追加 /手動で追加する必要があります）。
Option.LocalAddress ：発信接続のためにバインドするローカルインターフェイス文字列
option.changeorigin ：true/false、default：false-ホストヘッダーの原点をターゲットURLに変更する
option.preserveheaderkeycase ：true/false、default：false-応答ヘッダーキーの文字ケースを維持するかどうかを指定します
option.auth ：基本認証IE 'ユーザー：パスワード'認証ヘッダーを計算します。
option.hostrewrite ：（301/302/307/308）リダイレクトでロケーションホスト名を書き直します。
option.autorewrite ：要求されたホスト/ポートに基づいて、（301/302/307/308）リダイレクトでロケーションホスト/ポートを書き換えます。デフォルト：false。
option.protocolrewrite ：（301/302/307/308）の位置プロトコルを「http」または「https」に書き換えます。デフォルト：null。
option.CookiedOmainrewrite ： set-cookieヘッダーのドメインを書き直します。考えられる値：
false （デフォルト）：Cookie書き換えを無効にします
文字列：たとえば、 cookieDomainRewrite: "new.domain" 。ドメインを削除するには、 cookieDomainRewrite: ""を使用します。
オブジェクト：ドメインの新しいドメインへのマッピングは、 "*"を使用してすべてのドメインを一致させます。
たとえば、1つのドメインを変更せずに保持し、1つのドメインを書き直し、他のドメインを削除します。
cookieDomainRewrite: {
"unchanged.domain" : " unchanged.domain " ,
"old.domain" : " new.domain " ,
"*" : " "
} option.CookiePathrewRite ： set-cookieヘッダーのパスを書き直します。考えられる値：
false （デフォルト）：Cookie書き換えを無効にします
文字列：新しいパス、たとえばcookiePathRewrite: "/newPath/" 。パスを削除するには、 cookiePathRewrite: ""を使用します。ルートにパスを設定するにはcookiePathRewrite: "/"を使用します。
オブジェクト：新しいパスへのパスのマッピングは、 "*"を使用してすべてのパスを一致させます。たとえば、1つのパスを変更せずに保持するには、1つのパスを書き換えて、他のパスを削除します。
cookiePathRewrite: {
"/unchanged.path/" : " /unchanged.path/ " ,
"/old.path/" : " /new.path/ " ,
"*" : " "
} Option.Headers ：オブジェクト、リクエストヘッダーを追加します。 （例： {host:'www.example.org'} ）
option.proxytimeout ：Proxyがターゲットから応答を受け取らないときのタイムアウト（ミリ）
Option.TimeOut ：着信要求のためのタイムアウト（ミリ）
option.followRedirects ：true/false、default：false-リダイレクトをフォローするかどうかを指定する
option.Selfhandleresponse true/false、Trueに設定されている場合、WebOutoveringパスはいずれも呼び出されませんproxyRes
Option.Buffer ：リクエスト本文として送信するデータのストリーム。たとえば、リクエストストリームをプロキシを使用する前に、リクエストストリームを消費するミドルウェアがあるかもしれません。リクエストの本文を「req.rawbody」と呼ばれるフィールドに読んだ場合、バッファーオプションでこのフィールドを制限することができます。
'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 } ) ;以前のWebSocketの例では、HTTP-Proxy-Middlewareは、HTTP upgradeイベントを聞くために、初期のHTTPリクエストに依存しています。最初のHTTP要求なしにWebSocketsをプロキシする必要がある場合は、サーバーのHTTP upgradeイベントを手動で購読できます。
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' createProxyMiddlewareでonProxyReq定義することにより、下流からの要求を傍受します。
現在、事前に提供された要求インターセプターはfixRequestBodyです。これは、このミドルウェアの前にbodyParserが適用されたときにプロキシされたPOSTリクエストを修正するために使用されます。
例：
const { createProxyMiddleware , fixRequestBody } = require ( 'http-proxy-middleware' ) ;
const proxy = createProxyMiddleware ( {
/**
* Fix bodyParser
**/
on : {
proxyReq : fixRequestBody ,
} ,
} ) ; responseInterceptorを使用した上流からの応答を傍受します。 （必ずselfHandleResponse: true ）
brotli 、 gzip 、およびdeflateで圧縮される応答は、自動的に減圧されます。応答は、操作できるbuffer （docs）として返されます。
bufferでは、応答操作はテキスト応答（HTML/CSS/JSなど）に限定されません。画像操作も可能です。 （例）
注： responseInterceptor 、ターゲットの応答のストリーミングを無効にします。
例：
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
} ) ,
} ,
} ) ;その他の例については、インターセプトレシピをご覧ください。
node.js 17+は、DNSルックアップに対してIPv6よりもIPv4を好みなくなりました。たとえば::1 localhost 127.0.0.1に解決されることは保証されていません。
ターゲットサーバーがIPv4接続のみを受け入れる場合、 ::1 （IPv6）に解決した場合、 localhostにプロキシを試みることは失敗します。
それを解決する方法：
target: "http://localhost"はtarget: "http://127.0.0.1"になります。nodeを実行するときにこのフラグを追加： node index.js --dns-result-order=ipv4first 。 （お勧めしません。）注：Happy Eyeballsと呼ばれるものがあります。これは、IPv4とIPv6の両方に並行して接続することを意味します。Node.jsはありませんが、たとえば
curlが接続できる理由を説明しています。
DEBUG環境変数を設定して、デバッグロギングを有効にします。
その他のオプションについては、 debugプロジェクトを参照してください。
DEBUG=http-proxy-middleware * node server.js
$ http-proxy-middleware proxy created +0ms
$ http-proxy-middleware proxying request to target: ' http://www.example.org ' +359ms動作の例を見て遊んでください。
一般的なユースケースのレシピを表示します。
http-proxy-middleware次のサーバーと互換性があります。
サンプルの実装は、サーバーレシピに記載されています。
テストスイートを実行します：
# 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 spellcheckMITライセンス（MIT）
Copyright（c）2015-2024 Steven Chim
