企业官网建设流程全解析

express-useragent的Agent指纹字段全解：isMobile、isBot等60+布尔标志一次看懂

【免费下载链接】express-useragentNodeJS user-agent middleware项目地址: https://gitcode.com/gh_mirrors/ex/express-useragent

express-useragent 是一个基于 Node.js 的 User-Agent 解析库，自带 Express 中间件和 TypeScript 类型定义。它的核心能力是把一串晦涩的 User-Agent 文本，变成一个结构化的"Agent 指纹"对象（Agent），其中包含isMobile、isBot、isDesktop、isiPhone、isChrome等 60 多个布尔标志，让你无需写正则、不用猜设备，就能准确判断请求来自手机、平板、爬虫还是桌面浏览器。本文带你一次性看懂这些字段。

什么是 Agent 指纹？

当浏览器访问你的网站时，会在 HTTP 头里附上一段 User-Agent 字符串，例如：

Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 ...

express-useragent 会解析这段字符串，输出一个字段齐全的指纹对象，字段定义见src/express-useragent.ts中的AgentDetails接口（L129-L194）。其中最实用的就是那批isXXX布尔标志——每个标志都是一个"是/否"判断题，直接可用。

如何拿到完整指纹：两种最快接入方式

方式一：直接解析（适合任意 Node 服务）

import { UserAgent } from 'express-useragent'; const parser = new UserAgent().hydrate(uaString); console.log(parser.Agent.isMobile); // true / false

方式二：Express 中间件（推荐）

import express from 'express'; import { express as useragent } from 'express-useragent'; const app = express(); app.use(useragent()); app.get('/', (req, res) => { res.json({ browser: req.useragent?.browser, isMobile: req.useragent?.isMobile, isBot: req.useragent?.isBot, }); });

中间件会把指纹挂到req.useragent和res.locals.useragent上，实现代码位于src/index.ts的express()函数（L29-L60）。完整可运行的示例在examples/server.ts。

布尔标志分类速查表 📋

字段太多记不住？按"设备类型 → 系统 → 浏览器 → 爬虫"四组记，覆盖全部核心标志：

1️⃣ 设备类型标志：判断手机、平板、桌面

💡 注意：isMobile为true时isDesktop必为false，两者互斥，见src/express-useragent.ts的testMobile()方法（L809-L851）。

2️⃣ 操作系统与设备标志：精确到设备型号

3️⃣ 浏览器标志：识别客户端身份

4️⃣ 爬虫标志：区分人与机器 🤖

爬虫检测支持 Client Hints 与 UA 双通道；TikTok WebView 中包含 "googleplay" 字样曾被误判为 Google 爬虫，源码中已专门处理该误报（testBot()方法 L776-L803）。大量真实爬虫样本可参考tests/bots.test.ts。

实战示例：读懂一条 iPhone Safari 请求

用下面这条真实 UA 解析后（示例输出结构参考 README 中的 Sample payload）：

{ "isMobile": true, "isDesktop": false, "isBot": false, "isiPhone": true, "isWebkit": true, "isSafari": true, "isMac": true, "browser": "Safari", "os": "iOS", "platform": "iPhone" }

📌 有个经典"坑"：iPhone UA 里含有like Mac OS X，所以isMac也会为true——这是 UA 格式的历史遗留，判断设备类型时优先看isiPhone和isMobile。

三个新手最常踩的坑 ⚠️

1. isTablet不等于"非手机"：平板与手机标志可能同时需要单独判断，testTablet()会综合 iPad、Android 平板和 Kindle Fire 得出结论（L859-L867）。
2. isBot为true时看botName：布尔值只告诉你"是爬虫"，botName才告诉你"是哪个爬虫"，方便做针对性拦截或放行。
3. 带请求头解析更准：new UserAgent().hydrateFromHeaders(ua, headers)会额外解析 User-Agent Client Hints 头，能识别靠 UA 字符串识别不出的浏览器（如 Chromium 版 DuckDuckGo），推荐优先使用。

相关代码位置

• 核心解析器与全部字段定义：src/express-useragent.ts
• Express 中间件实现：src/index.ts
• 爬虫/Android/macOS 等分类测试用例：tests/bots.test.ts、tests/android.test.ts、tests/macos.test.ts
• 浏览器端使用入口：src/browser.ts
• 快速上手示例：examples/simple.ts、examples/server.ts、examples/http.ts

小结

express-useragent 的 Agent 指纹把"猜设备"变成"查字段"：设备类型组（isMobile / isTablet / isSmartTV）管分流，操作系统组（isMac / isWindows / isAndroid）管适配，浏览器组（isChrome / isSafari / isWechat）管兼容，爬虫组（isBot / botName / isCurl）管安全。配合 Express 中间件一行接入，你的站点就能对每一位访问者"一目了然"。

【免费下载链接】express-useragentNodeJS user-agent middleware项目地址: https://gitcode.com/gh_mirrors/ex/express-useragent