# get-client-ip 中文文档 规范地址：https://npmcn.com/package/get-client-ip/ 版本：5\.0\.0 npm 元数据更新时间：2026-11-03T17:12:04.634Z 中文译文更新时间：2026-11-03T18:09:02.221Z 软件包许可：MIT 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/get-client-ip 原文对照：https://npmcn.com/package/get-client-ip/?lang=original 项目主页：https://github.com/WolfieLeader/npm/tree/main/packages/get-client-ip#readme 源码仓库：https://github.com/WolfieLeader/npm ## 关键信息（来自 npm 元数据） - 包体积（解压后）：109 kB，9 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22\.12\.0 - 运行依赖：0 个 - 首次发布：2022-10-11T16:53:34.252Z - 最新版本发布：2026-11-03T17:12:04.322Z - 已发布版本数：30（近 12 个月 5 个） ## 中文简介 📍从传入HTTP请求中提取真实客户端IP地址的轻量级实用程序 ## 安装 ```sh npm install get-client-ip ``` 也可以使用：`pnpm add get-client-ip`、`yarn add get-client-ip`、`bun add get-client-ip` ## README ![banner](https://github.com/WolfieLeader/npm/blob/main/assets/get-client-ip-banner.svg) # get-client-ip 从HTTP请求中提取真实的客户端IP，安全地放在代理后面。 独立工作或作为Express/NestJS中间件。 [![License](https://img.shields.io/github/license/WolfieLeader/npm?color=DC343B)](https://opensource.org/licenses/MIT) [![npm version](https://img.shields.io/npm/v/get-client-ip?color=0078D4)](https://www.npmjs.com/package/get-client-ip) [![npm downloads](https://img.shields.io/npm/dt/get-client-ip.svg?color=03C03C)](https://www.npmjs.com/package/get-client-ip) [![stars](https://img.shields.io/github/stars/WolfieLeader/npm)](https://github.com/WolfieLeader/npm) ## 亮点✨ - **Spoof-resistant** - - - - - -走 `X-Forwarded-For` 从右边，停在第一个不受信任的跃点，如Express `trust proxy` - **无需框架即可工作** -raw `node:http`,高雅 `ctx.req`， Next.js页面API， Express v4/v5, fasttify, NestJS - **选择加入供应商标题** - - - - - - `cf-connecting-ip`， `true-client-ip`,和类似的是只读的，当你列出它们 - **RFC 7239 `Forwarded`** -引用字符串，IPv6，端口， `unknown`，以及混淆的标识符 - **CIDR信任列表** —比较解析后的IPv4地址和IPv6地址 - **归一化输出** - - - - - - `::ffff:1.2.3.4` 变成了 `1.2.3.4`;IPv6是小写和压缩的 ## 安装📦 需要Node.js >= 22.12。 ```bash npm install get-client-ip # or pnpm add get-client-ip ``` ## 快速启动🚀 ```typescript import express from "express"; import { getClientIp } from "get-client-ip"; const app = express(); // Middleware — populates req.clientIp and req.clientIps app.use(getClientIp); app.get("/me", (req, res) => { res.json({ ip: req.clientIp, ips: req.clientIps }); }); // Or standalone — call directly in a route app.get("/ip", (req, res) => { res.json({ ip: getClientIp(req) }); }); app.listen(3000); ``` 无框架的： ```typescript import http from "node:http"; import { getClientIp } from "get-client-ip"; http.createServer((req, res) => res.end(getClientIp(req))).listen(3000); ``` ## API参考📖 ### `getClientIp(req, options?): string | undefined` 返回客户端IP，或 `undefined` 当没有地址是已知的。也设置 `req.clientIp` 和 `req.clientIps`． 如果扔 `req` 缺少或 `options` 是无效的。 直接传递给 `app.use(getClientIp)` 将其作为带有默认选项的中间件运行。 ### `getClientIpMiddleware(options?)` 返回 `(req, res, next)` 使用的中间件 `options`． 它验证 `options` 一次，在创作。 ```typescript import { DEFAULT_TRUSTED_PROXIES, getClientIpMiddleware } from "get-client-ip"; app.use(getClientIpMiddleware({ trustedProxies: [...DEFAULT_TRUSTED_PROXIES, "203.0.113.0/24"] })); ``` ### 选项 | 选项 | 类型 | 默认的 | 描述 | | --- | --- | --- | --- | | `trustedProxies` | `string[]` | `DEFAULT_TRUSTED_PROXIES` | 您信任其转发头的代理的ip或cidr。 `[]` 不信任任何人。 | | `forwardedHeader` | `"x-forwarded-for" | "forwarded"` | `"x-forwarded-for"` | 代理附加到的标头。另一个被忽略。 | | `trustedHeaders` | `string[]` | `[]` | 单IP标头您的边缘总是覆盖，例如. `["cf-connecting-ip"]`． 按顺序检查。 | `DEFAULT_TRUSTED_PROXIES` 是 `127.0.0.0/8`， `10.0.0.0/8`， `172.16.0.0/12`， `192.168.0.0/16`， `169.254.0.0/16`， `::1/128`， `fc00::/7`, `fe80::/10`。CGNAT (`100.64.0.0/10`) 不受信任。 ### `req.clientIp` 和 `req.clientIps` ```typescript req.clientIp; // string | undefined — the client IP req.clientIps; // [string, ...string[]] | undefined — the client, then each trusted hop toward your server ``` 包裹增加了快递 `Request` 类型，因此不需要手动声明。 ## 如何解析IP📋 1. **`trustedHeaders`** -仅当套接字对等体是可信代理时，从列出的标头中获得第一个有效IP。 2. **`req.ip`** -当它是一个有效的IP外 `trustedProxies`． Express和fasttify从它们自己的信任设置中设置它。 - 如果 `req.ip` 本身是一个受信任的代理 (例如，没有 `trust proxy` 在nginx之后，它是代理，而不是客户端。像步骤4一样遍历链。 `req.ip` 仅当未找到不受信任的跃点时才保留。 3. **套接字地址** -当套接字对等体不是受信任的代理时，将忽略标头。 4. **转发链** ——读 `X-Forwarded-For` (或 `Forwarded`) 从右边。跳过每个受信任的代理。返回第一个不受信任的地址。 - 如果每个跳都是可信的，则返回最左边的跳。 - 一个 `unknown`，混淆的(`_hidden`)，或无效跳停止行走。返回最近的可信跳。 示例: nginx on `10.0.0.5` 附加它看到的peer。客户端发送 `X-Forwarded-For: 6.6.6.6`,所以你的应用程序接收 `6.6.6.6, 203.0.113.9`。结果是 `203.0.113.9`,不是恶搞的 `6.6.6.6`。 ## 部署指南🧭 | 设置 | 配置 | | --- | --- | | nginx、HAProxy或私有IP上的负载均衡器 | 违约 | | 代理背后的快递 | 默认工作; 设置Express [`trust proxy`](https://expressjs.com/en/guide/behind-proxies.html) 同样适用 | | 私有负载均衡器前面的Cloudflare | `{ trustedHeaders: ["cf-connecting-ip"] }` | | 写rfc7239的代理 `Forwarded` | `{ forwardedHeader: "forwarded" }` | | 公共IP上的代理 | `{ trustedProxies: [...DEFAULT_TRUSTED_PROXIES, ""] }` | | 直接在互联网上 | `{ trustedProxies: [] }` | ## NestJS🧩 ```typescript import { Controller, Get, Req } from "@nestjs/common"; import type { Request } from "express"; import { getClientIp } from "get-client-ip"; @Controller() export class AppController { @Get("ip") getIp(@Req() req: Request) { return { ip: getClientIp(req) }; } } ``` ## 安全🛡️ - **仅列出您的边缘覆盖的标头。** 一个 `trustedHeaders` 入口由客户端控制，除非每个请求都经过该边缘。让你的原点只能通过它到达。 - **选择代理写入的标头。** 如果您的代理追加 `X-Forwarded-For`,一个客户端发送的 `Forwarded` Header被忽略，反之亦然。 - **受信任范围内的客户端可以欺骗。** 受信任网络上的主机可以发送任何 `X-Forwarded-For`． 狭窄的 `trustedProxies` 到你代理的地址。 - **一个不受信任的 `req.ip` 是可信的。** 如果您的框架的代理信任比 `trustedProxies`， `req.ip` 可以来自客户端提供的标头。 ## v5中的重大更改⚠️ - **需要Node.js >= 22.12。** - **`X-Forwarded-For` 从右边读。** v4返回最左边的条目，任何客户端都可以设置。现在返回右侧的第一个不受信任的跃点。 - **供应商头需要选择加入。** `cf-connecting-ip`， `true-client-ip`， `fastly-client-ip`， `x-appengine-user-ip`， `cf-pseudo-ipv4`， `x-client-ip`， `x-real-ip`， `x-cluster-client-ip`， `forwarded-for`, `x-forwarded` 被忽略，除非列在 `trustedHeaders`。 - **受信任的 `req.ip` 不再赢了。** 当 `req.ip` 在里面 `trustedProxies` (表达不 `trust proxy` 在私有或环回代理之后)，转发链被走。v4返回了代理的地址。通过 `trustedProxies: []` 以保留v4结果。 - **`Forwarded` 需要选择加入。** 集 `forwardedHeader: "forwarded"`。 `X-Forwarded-For` 然后被忽略。 - **第二个论点是现在 `options`。** `getClientIp(req, res)` 不再意味着中间件; 使用 `getClientIp(req, res, next)`， `app.use(getClientIp)`,或 `getClientIpMiddleware()`。 - **`req.clientIps` 改变的意义。** 它是客户端，后面是指向服务器的可信跃点，最后是套接字对等端。v4列出了每个标题条目。 - **输出归一化。** ipv4 -映射IPv6 (`::ffff:1.2.3.4`) 成为IPv4，包括 `req.ip`． IPv6是小写和压缩的，它的区域ID被删除(`fe80::1%eth0` 变成了 `fe80::1`）. - **一个引用 `X-Forwarded-For` 表项是无效的一跳。** 中去掉了引号 `"203.0.113.9"`。代理从不引用它，所以引用的条目是客户端编写的，并停止行走。 - **中间件总是设置 `req.clientIp`。** 它是 `undefined` 当没有地址解析时。v4保持不变。 - **IPv6 trust使用真实CIDR匹配。** `fc::1` 不再受信任 (它不在 `fc00::/7`）. `fe80::/10` 现在覆盖 `fe80::`\-`febf::`。 - **`0.0.0.0` 和 `::` 是无效跳数。** ## 致谢🙏 灵感来自 [佩博吉诺夫的](https://github.com/pbojinov) 处理客户端IP检测。 ## 贡献🤝 - 打开一个 [问题](https://github.com/WolfieLeader/npm/issues) 或者特性请求 - 提交PR以改进包装 - 如果你觉得它有用，就用星号标记它 精心制作 [WolfieLeader](https://github.com/WolfieLeader) 该项目根据 [麻省理工学院的许可](https://opensource.org/licenses/MIT)。 ## 常见问题 ### get-client-ip 是什么？ 📍从传入HTTP请求中提取真实客户端IP地址的轻量级实用程序 ### 如何安装 get-client-ip？ 在项目目录运行 npm install get-client-ip，或使用 pnpm add / yarn add / bun add。 ### get-client-ip 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### get-client-ip 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### get-client-ip 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### get-client-ip 可以商用吗？ get-client-ip 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### get-client-ip 还在维护吗？ 最新版本 5\.0\.0 发布于 2026/11/04（今天）；至今共发布 30 个版本，其中过去 12 个月发布了 5 个；首次发布于 2022/10/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。