You need to enable JavaScript to run this app. Next.js服务端渲染场景下如何区分用户是PC端还是移动端
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.30 05:54:03