Next.js服务端渲染场景下如何区分用户是PC端还是移动端
Next.js 服务端获取User-Agent、区分PC/移动端的实现方案
核心澄清:Next.js 的服务端渲染流程本身是完全可以拿到真实请求的UA信息的,绝大多数拿不到的场景都是代码执行位置不对、渲染模式配错导致的,不存在“SSR流程天然屏蔽UA”的问题。
一、不同渲染架构下UA的获取路径
1. App Router 架构
服务端上下文(Server Component、Route Handler、嵌套Server Action)可以直接通过Next.js提供的headers API读取真实请求头:
// 在Server Component内执行(文件最顶部标记'use server'的组件除外) import { headers } from 'next/headers'; export default async function Page() { // 直接读取原始请求的UA字段 const userAgent = headers().get('user-agent'); // 后续直接做设备判断逻辑 const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini|HarmonyOS/i.test(userAgent || ''); return <div>当前访问设备为:{isMobile ? '移动端' : 'PC端'}</div> }
- 注意:如果当前页面是纯静态生成(SSG),上述代码会在构建期执行,不存在请求上下文,自然读不到UA。这时候只需要在文件内加一行
export const dynamic = 'force-dynamic',强制开启动态渲染即可恢复UA读取能力。 - 不要把这段headers读取逻辑放到客户端组件里执行,客户端上下文没有服务端请求对象,必然返回undefined。
2. Pages Router 架构
直接在服务端数据获取函数内从请求对象上读取UA即可:
export async function getServerSideProps(context) { // 从请求上下文拿原生UA const userAgent = context.req.headers['user-agent']; const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini|HarmonyOS/i.test(userAgent || ''); // 把判断结果作为props传给页面组件 return { props: { isMobile } } }
- 如果页面用了
getStaticProps做静态生成,是拿不到运行时UA的,要么替换成getServerSideProps,要么用Middleware方案做设备分流。
3. 通用Middleware分流方案
如果需要在路由访问最前置的阶段做设备判断(比如根据设备跳转到不同版本的页面),可以直接在项目根目录的middleware.ts里读取请求头,完全不依赖页面的渲染模式:
import { NextResponse } from 'next/server'; export function middleware(request) { const userAgent = request.headers.get('user-agent'); const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini|HarmonyOS/i.test(userAgent || ''); // 可以基于判断结果重写路由、设置自定义header const requestHeaders = new Headers(request.headers); requestHeaders.set('x-device-type', isMobile ? 'mobile' : 'pc'); return NextResponse.next({ request: { headers: requestHeaders, }, }); }
- 后续所有页面组件、服务端逻辑都可以直接读取这个自定义的
x-device-type头,不用重复写UA判断逻辑。
二、设备判断的常见踩坑点
- 不要只匹配
/Mobile/这一个字符串,很多PC浏览器的UA也会带Mobile标识,容易误判 - 要额外适配iPadOS 13+的特殊情况:这部分设备的默认UA和Mac桌面端完全一致,常规正则匹配不到,如果要精准识别平板设备,可以读取请求头里的
Sec-CH-UA-Mobile、Sec-CH-Platform等现代浏览器客户端提示字段做判断 - 如果项目前面加了CDN、反向代理,要确认代理配置会把真实用户的UA头透传到Next.js服务,不然拿到的都是代理节点的内置UA
- 做SSR hydration的时候,前后端的设备判断逻辑要完全统一,不然会出现服务端渲染的设备类名和客户端判断结果不一致,触发hydration mismatch报错
内容的提问来源于stack exchange,提问作者user15413207
相关产品推荐
相关产品推荐

