const visualViewport = window.visualViewport

visualViewport?.addEventListener('resize', () => {
  console.log({
    width: visualViewport.width,
    height: visualViewport.height,
    offsetTop: visualViewport.offsetTop,
    scale: visualViewport.scale
  })
})

普通布局不应依赖 JavaScript 读取视觉视口。只有需要处理软键盘、浮层避让等场景时，才考虑使用 visualViewport。

2.3 初始视口和“理想视口”

移动端常说的“理想视口”不是一个需要单独调用的浏览器 API，通常是指通过 width=device-width 和初始缩放设置，让布局宽度匹配设备的 CSS 像素宽度。

正确设置 viewport 后，页面通常不需要再依赖浏览器默认的虚拟宽度进行缩放。

三、CSS 像素、设备像素和 DPR

3.1 CSS 像素

CSS 中的 px 是 CSS 像素，也称逻辑像素。它不是屏幕硬件像素的直接等价物。

.box {
  width: 100px;
  height: 100px;
}

这表示元素的 CSS 尺寸为 100 × 100，不代表屏幕一定使用 100 × 100 个物理像素显示它。

3.2 设备像素

设备像素是屏幕硬件实际拥有的像素点。高密度屏幕可能使用多个设备像素显示一个 CSS 像素。

3.3 设备像素比 DPR

DPR（Device Pixel Ratio）表示设备像素与 CSS 像素之间的比例：

DPR = 设备像素数量 / CSS 像素数量

可以通过 JavaScript 获取：

console.log(window.devicePixelRatio)

例如某设备的 CSS 宽度为 375px，DPR 为 3，物理屏幕宽度可能约为 1125 个设备像素。但开发者布局时仍然主要面对 375px 的 CSS 视口。

不要把屏幕分辨率、DPR 和 CSS 视口宽度混为一谈。移动端适配通常优先解决 CSS 布局问题，而不是直接按照物理像素布局。

四、正确设置 viewport

推荐使用：

<meta name="viewport" content="width=device-width, initial-scale=1">

各参数含义：

参数	作用
`width=device-width`	让布局视口宽度匹配设备 CSS 宽度
`initial-scale=1`	设置初始缩放比例为 1
`height=device-height`	很少需要显式设置，通常不建议依赖
`user-scalable`	控制用户缩放，不建议禁止
`minimum-scale` / `maximum-scale`	限制缩放范围，不建议随意设置

不建议使用：

<meta
  name="viewport"
  content="width=device-width, initial-scale=1, user-scalable=no, maximum-scale=1"
>

禁止缩放会影响用户，尤其是低视力用户。除非有非常明确且经过无障碍评估的特殊需求，否则应允许用户缩放页面。

五、移动端适配的基本原则

5.1 先解决布局，再考虑单位转换

优先使用浏览器原生布局能力：

Flexbox；
CSS Grid；
百分比；
min-width 和 max-width；
min()、max() 和 clamp()；
媒体查询和容器查询。

不要先把所有 px 转换成 rem 或 vw，再试图用单位转换解决布局问题。

5.2 设置合理的内容宽度

移动端页面可以占满屏幕，平板和桌面端则通常需要限制阅读宽度：

.page {
  width: min(100% - 32px, 1200px);
  margin-inline: auto;
}

5.3 使用统一的盒模型

*,
*::before,
*::after {
  box-sizing: border-box;
}

这样设置后，元素的 width 和 height 会包含 padding 与 border，更容易计算布局尺寸。

5.4 不要把固定尺寸全部视为错误

以下内容通常可以使用固定 CSS 像素：

边框宽度；
图标尺寸；
最小点击区域；
小范围内的间距；
某些需要保持清晰的 1px 视觉边框。

是否使用 px、rem 或 vw，应根据内容和布局需求决定。

六、常见适配方案

6.1 响应式布局：优先使用 CSS

百分比并不是“不推荐”的方案。不同 CSS 属性的百分比参照物可能不同，但只要理解规则，百分比非常适合响应式布局。

.container {
  width: min(100%, 960px);
  margin-inline: auto;
  padding-inline: 16px;
}

.card-list {
  display: grid;
  grid-template-columns: repeat(
    auto-fit,
    minmax(min(100%, 280px), 1fr)
  );
  gap: 16px;
}

这段代码不需要知道具体设备型号，在不同可用宽度下会自动调整列数。

Flex 示例：

.header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 16px;
  flex-wrap: wrap;
}

.header__title {
  min-width: 0;
  overflow-wrap: anywhere;
}

6.2 rem 适配

rem 相对于根元素 html 的 font-size：

html {
  font-size: 16px;
}

.box {
  width: 10rem;
}

此时 10rem = 160px。如果通过 JavaScript 或媒体查询改变根字号，rem 尺寸也会随之改变。

方案一：媒体查询设置根字号

html {
  font-size: 16px;
}

@media (min-width: 375px) {
  html {
    font-size: 18px;
  }
}

@media (min-width: 768px) {
  html {
    font-size: 20px;
  }
}

这种方法简单，但断点数量有限，尺寸不会连续变化。

方案二：动态计算根字号

如果设计稿宽度是 375px，可以约定：

1rem = 37.5px

设计稿中的 100px 转换为：

100 / 37.5 = 2.6667rem

基础实现：

(() => {
  const DESIGN_WIDTH = 375
  const MAX_WIDTH = 750
  const root = document.documentElement

  function updateRootFontSize() {
    const width = Math.min(root.clientWidth, MAX_WIDTH)
    root.style.fontSize = `${width / 10}px`
  }

  updateRootFontSize()
  window.addEventListener('resize', updateRootFontSize)
  window.addEventListener('pageshow', updateRootFontSize)
})()

页面还应为正文设置合理的字号，避免根字号变化导致普通文字过大或过小：

body {
  font-size: 16px;
}

rem 尺寸换算示意图

rem 根字号示意表

rem 方案的注意事项

需要统一设计稿基准宽度；
需要处理大屏最大宽度；
不要把所有字体都机械转换为 rem；
不要禁止用户缩放；
动态修改根字号可能影响第三方组件和无障碍字体设置；
现代项目中，clamp() 和 CSS 原生流式布局通常可以减少 JavaScript 依赖。

使用 Sass 进行转换

@use 'sass:math';

@function px-to-rem($px, $base: 37.5px) {
  @return math.div($px, $base) * 1rem;
}

.card {
  width: px-to-rem(100px);
  padding: px-to-rem(16px);
}

6.3 vw、vh 和动态视口单位

vw 和 vh 是相对于视口的单位：

1vw 等于视口宽度的 1%；
1vh 等于视口高度的 1%；
100vw 约等于视口宽度；
100vh 在移动端可能受浏览器地址栏变化影响。

如果设计稿宽度为 375px，设计稿中的 100px 转换为：

100 / 375 × 100 = 26.6667vw

.box {
  width: 26.6667vw;
  aspect-ratio: 1;
}

使用 `clamp()` 限制范围

vw 并不是无法设置最大值和最小值，可以使用 clamp()：

.title {
  font-size: clamp(20px, 5vw, 36px);
}

.panel {
  width: clamp(280px, 80vw, 720px);
}

`svh`、`lvh` 和 `dvh`

移动端浏览器的地址栏可能动态展开和收起，因此 100vh 不一定等于当前真正可见的高度。现代 CSS 提供了三类视口高度单位：

单位	含义	适合场景
`svh`	小视口高度	保证内容不会被浏览器 UI 遮挡
`lvh`	大视口高度	需要填满浏览器 UI 收起后的最大区域
`dvh`	动态视口高度	需要匹配当前可见高度的界面

例如：

.hero {
  min-height: 100svh;
}

.chat-page {
  min-height: 100dvh;
}

dvh 会随着浏览器 UI 变化而变化，可能带来布局移动。对于重要页面，应根据实际交互测试后选择单位。

6.4 PostCSS 自动转换

`postcss-pxtorem`

postcss-pxtorem 将 CSS 中的 px 转换为 rem，rootValue 表示转换基准：

// postcss.config.cjs
module.exports = {
  plugins: {
    'postcss-pxtorem': {
      rootValue: 37.5,
      propList: ['font', 'font-size', 'line-height', 'letter-spacing'],
      selectorBlackList: ['.ignore-rem'],
      minPixelValue: 2
    }
  }
}

如果希望转换 width、padding、margin 等属性，需要把它们加入 propList，但不建议无条件转换所有属性：

propList: ['*']

边框、阴影、第三方组件和动画值往往需要单独处理。

`postcss-px-to-viewport`

该类插件将 px 转换为 vw，核心配置是设计稿宽度 viewportWidth，不是 rootValue：

// postcss.config.cjs
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
      unitPrecision: 5,
      propList: ['*'],
      viewportUnit: 'vw',
      fontViewportUnit: 'vw',
      selectorBlackList: ['.ignore-vw'],
      minPixelValue: 1,
      mediaQuery: false
    }
  }
}

使用这类插件前，应确认插件的维护状态、构建工具兼容性以及项目是否真的需要全局单位转换。对于新项目，CSS 原生 clamp()、Flex 和 Grid 往往能减少对转换插件的依赖。

6.5 Flex 和 Grid

Flex 和 Grid 是布局工具，不是单独的“适配单位”。它们应与尺寸约束、媒体查询和流体单位结合使用。

.layout {
  display: flex;
  gap: 16px;
}

.sidebar {
  flex: 0 0 240px;
}

.content {
  min-width: 0;
  flex: 1 1 auto;
}

@media (max-width: 640px) {
  .layout {
    flex-direction: column;
  }

  .sidebar {
    flex-basis: auto;
  }
}

七、图片、字体和安全区域

7.1 图片响应式

img,
video {
  display: block;
  max-width: 100%;
  height: auto;
}

固定比例的图片可以使用：

.cover {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
  border-radius: 12px;
}

需要根据屏幕提供不同资源时，可以使用 <picture>：

<picture>
  <source media="(min-width: 768px)" srcset="/images/banner-large.webp">
  <img src="/images/banner-small.webp" alt="活动横幅">
</picture>

7.2 长文本和表格

.article {
  overflow-wrap: anywhere;
}

.table-wrapper {
  overflow-x: auto;
  -webkit-overflow-scrolling: touch;
}

不要为了让表格强行缩小到不可读的程度，可以允许表格在小屏幕上横向滚动。

7.3 刘海屏和安全区域

全面屏设备可能存在刘海、圆角或底部手势区域。使用 env() 读取安全区域：

.page {
  padding-top: max(16px, env(safe-area-inset-top));
  padding-right: max(16px, env(safe-area-inset-right));
  padding-bottom: max(16px, env(safe-area-inset-bottom));
  padding-left: max(16px, env(safe-area-inset-left));
}

如果页面使用全屏布局，还需要在 HTML 中设置适合的显示模式，并在真实设备上测试，不能只依赖浏览器开发者工具模拟。

7.4 触摸区域和字体

重要按钮应有足够的触摸区域，通常不小于约 44px；
不要仅通过颜色表达状态；
正文文字应允许用户缩放；
使用 line-height 提高移动端阅读体验；
避免把 font-size 设置为过小的值；
输入框字号过小时，部分移动浏览器可能自动放大页面。

八、媒体查询与容器查询

8.1 媒体查询

媒体查询可以根据视口宽度、方向和用户偏好调整布局：

.navigation {
  display: flex;
}

@media (max-width: 640px) {
  .navigation {
    display: none;
  }
}

@media (orientation: landscape) {
  .hero {
    min-height: 80svh;
  }
}

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

断点不应机械按照某几个具体手机型号设置。应根据内容在布局开始变得拥挤时设置断点。

8.2 容器查询

组件不一定总是根据整个页面视口调整，也可能根据所在容器宽度调整。容器查询适合可复用组件：

.card-list {
  container-type: inline-size;
}

.card {
  display: block;
}

@container (min-width: 480px) {
  .card {
    display: grid;
    grid-template-columns: 160px 1fr;
  }
}

九、Nuxt/Vue 项目实践

Nuxt 4、Vue 3 和 Vite 项目中，通常不需要引入额外的移动端适配库。可以把公共样式放在 app/assets/styles/，通过 CSS 原生能力完成适配。

基础样式示例：

:root {
  color-scheme: light;
  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

*,
*::before,
*::after {
  box-sizing: border-box;
}

body {
  margin: 0;
  min-width: 320px;
  font-size: 16px;
  line-height: 1.6;
}

button,
input,
textarea,
select {
  font: inherit;
}

在 Nuxt 页面中建议：

使用 Flex、Grid 和 CSS 变量组织布局；
使用 useHead() 设置 viewport，而不是在多个页面重复写；
通过 onMounted() 或客户端插件读取 window、visualViewport 等浏览器 API；
不要在 SSR 阶段读取 window.innerWidth；
如果必须根据客户端宽度渲染不同内容，注意避免服务端和客户端 hydration 不一致；
优先使用 CSS 媒体查询，而不是在 JavaScript 中监听 resize 后频繁修改 DOM。

设置 viewport 的示例：

useHead({
  meta: [
    {
      name: 'viewport',
      content: 'width=device-width, initial-scale=1'
    }
  ]
})

十、常见错误

1. 禁止用户缩放

错误：

<meta name="viewport" content="user-scalable=no, maximum-scale=1">

这会损害无障碍体验。除非有特殊且经过验证的业务原因，否则不要限制缩放。

2. 把所有 px 都转换成 rem 或 vw

边框、阴影、字体、动画和第三方组件不一定适合统一转换。应按属性和场景配置。

3. 用设备型号写大量媒体查询

不要写成：

/* 不建议围绕具体手机型号堆叠断点 */
@media (width: 375px) {}
@media (width: 390px) {}
@media (width: 414px) {}

应该根据内容布局是否需要变化设置断点，并优先使用流式布局。

4. 用 JavaScript 代替所有 CSS 响应式能力

频繁监听 resize 并修改大量内联样式可能导致性能问题和 hydration 问题。只有 CSS 无法解决的场景，才使用 JavaScript。

5. 把 `100vh` 当作当前可见高度

移动浏览器地址栏变化时，100vh 可能出现内容被遮挡或页面跳动。根据需求选择 100svh、100dvh 或 100lvh。

6. 忽略横向溢出

检查以下常见原因：

width: 100vw 包含滚动条宽度；
长文本没有换行；
图片没有 max-width: 100%；
Flex 子项缺少 min-width: 0；
固定宽度组件超出容器；
表格没有提供横向滚动容器。

7. 只在开发者工具中测试

浏览器模拟不能完全代替真实设备测试。应至少检查真实 iOS、Android、横屏、软键盘、系统字体放大和不同浏览器地址栏状态。

十一、如何选择方案

项目情况	推荐方案
普通页面布局	Flex/Grid + 百分比 + `max-width`
文章、后台、表单	`rem` 或固定 CSS 像素 + 响应式布局
设计稿尺寸需要连续缩放	`vw` 或 PostCSS 转换
字体需要平滑变化	`clamp()`
全屏移动端页面	`svh` / `dvh` + 安全区域
可复用组件	容器查询 + Flex/Grid
复杂设计稿还原	rem 或 vw 转换，但应配合最大宽度和异常值处理
Nuxt/Vue 新项目	CSS 原生能力优先，避免依赖旧版适配库

推荐的组合通常是：

viewport
  + CSS Reset
  + Flex / Grid
  + rem 或 vw（按项目需要）
  + clamp()
  + 媒体查询 / 容器查询
  + 图片和安全区域处理

十二、测试清单

发布前建议检查：

十三、总结

移动端适配首先要正确设置 viewport；
CSS 像素不等于设备物理像素，应区分 CSS 像素、设备像素和 DPR；
Flex、Grid、百分比和 max-width 应作为响应式布局基础；
rem 适合需要统一设计稿缩放的项目，但要控制根字号和文字大小；
vw 可以实现流体尺寸，但应配合 clamp()、最大值和最小值；
svh、dvh 和 lvh 可以改善移动端全屏高度适配；
不要使用 user-scalable=no 和 maximum-scale=1 阻止用户缩放；
图片、表格、长文本、横屏、软键盘和安全区域都属于适配范围；
Nuxt/Vue 项目应优先使用 CSS 原生能力，减少客户端 JavaScript 布局计算；
适配方案应根据内容和组件需求选择，而不是围绕具体设备型号堆叠规则。