ua-browser 1.3.1 → 1.4.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +226 -0
- package/README.md +93 -85
- package/dist/index.cjs +277 -44
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +82 -17
- package/dist/index.d.ts +82 -17
- package/dist/index.min.js +2 -2
- package/dist/index.min.js.map +1 -1
- package/dist/index.mjs +275 -45
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
- package/README.zh-CN.md +0 -200
package/README.zh-CN.md
DELETED
|
@@ -1,200 +0,0 @@
|
|
|
1
|
-
# ua-browser
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/ua-browser)
|
|
4
|
-
[](https://www.npmjs.com/package/ua-browser)
|
|
5
|
-
[](./LICENSE)
|
|
6
|
-
[](https://www.typescriptlang.org/)
|
|
7
|
-
|
|
8
|
-
通过 User Agent 检测浏览器、操作系统、设备类型、渲染内核、CPU 架构、爬虫、无头浏览器及小程序运行环境。零依赖，支持浏览器与 Node.js 双环境。
|
|
9
|
-
|
|
10
|
-
**[📖 文档](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)** · **[English](./README.md)**
|
|
11
|
-
|
|
12
|
-
## 特性
|
|
13
|
-
|
|
14
|
-
- **全面 UA 检测** — 浏览器、OS、渲染内核、设备类型（Mobile / Tablet / TV / PC）、CPU 架构、爬虫、无头浏览器
|
|
15
|
-
- **多信号架构检测** — `getEnvContext()` 采集 Client Hints、WebGL 渲染器、字体探针，精确区分 Apple Silicon 与 Intel Mac
|
|
16
|
-
- **SSR Client Hints** — `parseHeaders()` + `ACCEPT_CH`，在 Chrome / Edge 90+ 中实现服务端精准检测（CPU 架构、平台等）
|
|
17
|
-
- **AI 爬虫识别** — 内置 GPTBot、ClaudeBot、PerplexityBot、CCBot 等主流 AI 抓取机器人
|
|
18
|
-
- **零依赖** — 无任何运行时依赖，gzip 后体积极小
|
|
19
|
-
- **纯函数** — `parseUA()` 无全局状态，天然支持 SSR / Node.js
|
|
20
|
-
- **TypeScript** — 完整类型定义，`BrowserName`、`OsName` 等均为精确字面量联合类型
|
|
21
|
-
- **Tree-shakeable** — 所有功能按需导入，不引入多余代码
|
|
22
|
-
|
|
23
|
-
## 安装
|
|
24
|
-
|
|
25
|
-
```sh
|
|
26
|
-
npm i ua-browser
|
|
27
|
-
# pnpm
|
|
28
|
-
pnpm add ua-browser
|
|
29
|
-
# yarn
|
|
30
|
-
yarn add ua-browser
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
## 快速上手
|
|
34
|
-
|
|
35
|
-
```typescript
|
|
36
|
-
import uaBrowser from 'ua-browser'
|
|
37
|
-
|
|
38
|
-
const info = uaBrowser()
|
|
39
|
-
|
|
40
|
-
console.log(info)
|
|
41
|
-
// {
|
|
42
|
-
// browser: 'Chrome',
|
|
43
|
-
// version: '124.0.0.0',
|
|
44
|
-
// engine: 'Blink',
|
|
45
|
-
// os: 'Windows',
|
|
46
|
-
// osVersion: '10',
|
|
47
|
-
// device: 'PC',
|
|
48
|
-
// arch: 'x86_64',
|
|
49
|
-
// isWebview: false,
|
|
50
|
-
// isHeadless: false,
|
|
51
|
-
// isBot: false,
|
|
52
|
-
// botName: 'unknown',
|
|
53
|
-
// language: 'zh-CN',
|
|
54
|
-
// platform: 'Win32'
|
|
55
|
-
// }
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
> 传入自定义 UA 字符串：`uaBrowser('Mozilla/5.0 ...')`
|
|
59
|
-
|
|
60
|
-
## 使用
|
|
61
|
-
|
|
62
|
-
### 浏览器环境
|
|
63
|
-
|
|
64
|
-
```typescript
|
|
65
|
-
import uaBrowser from 'ua-browser'
|
|
66
|
-
|
|
67
|
-
const { browser, os, device } = uaBrowser()
|
|
68
|
-
|
|
69
|
-
if (device === 'Mobile') {
|
|
70
|
-
// 跳转移动版
|
|
71
|
-
}
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### Node.js / SSR
|
|
75
|
-
|
|
76
|
-
```typescript
|
|
77
|
-
import { parseUA } from 'ua-browser'
|
|
78
|
-
|
|
79
|
-
const ua = req.headers['user-agent'] ?? ''
|
|
80
|
-
const { browser, os, isBot } = parseUA(ua)
|
|
81
|
-
|
|
82
|
-
if (isBot) {
|
|
83
|
-
// 拦截或放行爬虫
|
|
84
|
-
}
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
### CDN
|
|
88
|
-
|
|
89
|
-
```html
|
|
90
|
-
<script src="https://cdn.jsdelivr.net/npm/ua-browser/dist/index.min.js"></script>
|
|
91
|
-
<script>
|
|
92
|
-
const { browser, os } = uaBrowser()
|
|
93
|
-
</script>
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
### 多信号架构检测
|
|
97
|
-
|
|
98
|
-
`getEnvContext()` 一次性采集 Client Hints、WebGL 渲染器等多维信号，可区分 Apple Silicon 与 Intel Mac：
|
|
99
|
-
|
|
100
|
-
```typescript
|
|
101
|
-
import { getEnvContext, parseUA } from 'ua-browser'
|
|
102
|
-
|
|
103
|
-
const ctx = await getEnvContext()
|
|
104
|
-
const result = parseUA(navigator.userAgent, { ctx })
|
|
105
|
-
|
|
106
|
-
console.log(result.arch) // 'arm64' 或 'x86_64'
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
### SSR Client Hints
|
|
110
|
-
|
|
111
|
-
通过响应头告知 Chrome / Edge 90+ 上报 Client Hints，再用 `parseHeaders` 在服务端精准解析：
|
|
112
|
-
|
|
113
|
-
```typescript
|
|
114
|
-
import { parseHeaders, ACCEPT_CH } from 'ua-browser'
|
|
115
|
-
|
|
116
|
-
// 第一次响应时写入 Accept-CH
|
|
117
|
-
res.setHeader('Accept-CH', ACCEPT_CH)
|
|
118
|
-
|
|
119
|
-
// 后续请求携带 Client Hints 后，精准识别架构等信息
|
|
120
|
-
const result = parseHeaders(req.headers)
|
|
121
|
-
console.log(result.arch) // 'x86_64'（来自 Sec-CH-UA-Arch）
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
### 精确区分 Windows 10 / 11
|
|
125
|
-
|
|
126
|
-
Windows 10 和 11 的 UA 字符串相同，需借助 Client Hints API 异步获取：
|
|
127
|
-
|
|
128
|
-
```typescript
|
|
129
|
-
import { parseUA, getWindowsVersion, getNavContext } from 'ua-browser'
|
|
130
|
-
|
|
131
|
-
const nav = getNavContext()
|
|
132
|
-
const windowsVersion = await getWindowsVersion(nav)
|
|
133
|
-
const result = parseUA(navigator.userAgent, { nav, windowsVersion })
|
|
134
|
-
|
|
135
|
-
console.log(result.osVersion) // '10' 或 '11'
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
## API
|
|
139
|
-
|
|
140
|
-
### 默认导出 `uaBrowser(ua?)`
|
|
141
|
-
|
|
142
|
-
在浏览器环境中自动注入 `navigator` 上下文（语言、平台、MIME 类型等）。
|
|
143
|
-
|
|
144
|
-
```typescript
|
|
145
|
-
uaBrowser() // 自动读取 navigator.userAgent
|
|
146
|
-
uaBrowser(customUA) // 传入自定义 UA，仍注入当前浏览器上下文
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
### 命名导出（按需引入）
|
|
150
|
-
|
|
151
|
-
```typescript
|
|
152
|
-
import {
|
|
153
|
-
parseUA, // 纯函数，适合 SSR / Node.js
|
|
154
|
-
getNavContext, // 读取当前浏览器 navigator 上下文
|
|
155
|
-
getWindowsVersion, // 异步精确区分 Windows 10 / 11
|
|
156
|
-
getLanguage, // 从 NavContext 获取浏览器语言
|
|
157
|
-
getEnvContext, // 采集所有浏览器环境信号（Client Hints、WebGL 等）
|
|
158
|
-
parseHeaders, // 从 HTTP 请求头解析 UA 及 Client Hints（SSR）
|
|
159
|
-
ACCEPT_CH, // 响应头常量，告知浏览器上报 Client Hints
|
|
160
|
-
isWebview, // 检测 Android Webview / iOS WKWebView
|
|
161
|
-
detectBot, // 独立爬虫检测
|
|
162
|
-
detectArch, // 独立 CPU 架构检测
|
|
163
|
-
detectHeadless, // 独立无头浏览器检测
|
|
164
|
-
VERSION, // 当前版本号
|
|
165
|
-
} from 'ua-browser'
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
### 返回值 `EnvOption`
|
|
169
|
-
|
|
170
|
-
| 字段 | 类型 | 说明 |
|
|
171
|
-
| :-- | :-- | :-- |
|
|
172
|
-
| `browser` | `BrowserName` | 浏览器名称 |
|
|
173
|
-
| `version` | `string` | 浏览器版本 |
|
|
174
|
-
| `engine` | `EngineName` | 渲染内核 |
|
|
175
|
-
| `os` | `OsName` | 操作系统 |
|
|
176
|
-
| `osVersion` | `string` | 系统版本 |
|
|
177
|
-
| `device` | `DeviceName` | 设备类型：`Mobile` \| `Tablet` \| `TV` \| `PC` |
|
|
178
|
-
| `arch` | `ArchName` | CPU 架构 |
|
|
179
|
-
| `isWebview` | `boolean` | 是否为 Android Webview / iOS WKWebView |
|
|
180
|
-
| `isHeadless` | `boolean` | 是否为无头 / 自动化浏览器 |
|
|
181
|
-
| `isBot` | `boolean` | 是否为爬虫 / 机器人 |
|
|
182
|
-
| `botName` | `BotName` | 爬虫名称 |
|
|
183
|
-
| `language` | `string` | 浏览器语言，如 `zh-CN` |
|
|
184
|
-
| `platform` | `string` | 平台标识，如 `Win32` |
|
|
185
|
-
|
|
186
|
-
> 所有字段在无法识别时统一返回 `'unknown'`，不返回空字符串或 `null`。
|
|
187
|
-
|
|
188
|
-
## 支持范围
|
|
189
|
-
|
|
190
|
-
内置超过 70 种浏览器、17 种操作系统、19 种爬虫规则，详见 **[内置支持列表](https://yangtianxia.github.io/ua-browser/guide/support-list)**。
|
|
191
|
-
|
|
192
|
-
部分覆盖：
|
|
193
|
-
- **浏览器** — Chrome、Safari、Firefox、Edge、Samsung Internet、UC、微信、钉钉、抖音、哔哩哔哩、快手、小红书、飞书等
|
|
194
|
-
- **操作系统** — Windows、macOS、Android、iOS、HarmonyOS、OpenHarmony、Tizen、KaiOS 等
|
|
195
|
-
- **AI 爬虫** — GPTBot、ClaudeBot、PerplexityBot、CCBot 等
|
|
196
|
-
- **设备** — Mobile、Tablet、TV（含三星 Smart TV、HbbTV 标准）、PC
|
|
197
|
-
|
|
198
|
-
## License
|
|
199
|
-
|
|
200
|
-
[MIT](./LICENSE) © yangtianxia
|