企业官网建设流程全解析

最近在做移动端 H5 项目时，设计师给的是 750 宽的设计稿，团队里有人习惯用 rem，有人习惯手算百分比，还有人直接写死 px 然后被各种机型打回来说“这里歪了”“那里溢出了”。折腾了几个版本之后，我决定把整个适配方案统一到一个思路上来：让 PostCSS 在构建阶段自动把 px 换算成 vw，也就是用 postcss-px-to-viewport 来做全局兜底。方案切完至今跑了大半年，线上没有出现一例因为适配导致的样式问题，这篇文章就把完整的落地过程、配置逻辑和踩过的坑一次说清楚。

这个方案适合谁用？主要面向三类人：一是做移动端 H5 页面、需要严格还原视觉稿的开发者；二是团队里适配规范混乱、每次联调都要靠人肉改样式的项目维护者；三是对 PostCSS 体系有一定了解、但想让构建流程自动化处理单位换算的前端工程师。文章不会只丢一个配置让你抄，而是把每一步的选择逻辑拆开讲明白，读完之后你不仅能配好这个插件，还能自己判断遇到新问题时该怎么调。

1. 为什么最终选了 px-to-viewport 这条适配路线

移动端适配的方案在社区里争论了很多年，主流的做法我基本都试过，这里先做个横向对比，你就知道为什么我最后锁定了 vw 方向。

1.1 其他常见适配方案的痛点对比

早期最流行的是 rem + 动态设置根字体大小，也就是 flexible 那套思路。它在 WebView 里通过 JavaScript 把 html 的 font-size 设置成屏幕宽度的十分之一，然后所有尺寸都用 rem 写。这套方案有两个很难受的副作用：一是页面加载时会有一小段的字体大小闪烁问题，因为 JS 执行需要时间；二是 rem 一定会牵涉到根字号，而根字号是会被用户浏览器的“字号设置”干扰的，尤其在部分安卓机型上，用户改了系统字体大小之后，整个页面布局会被拉伸甚至错乱。

后来有人尝试用纯媒体查询做响应式，但设计师给你的是固定宽度的视觉稿，媒体查询只适合处理少数断点，你没法为每一款机型写一套样式，代码量会爆炸，维护成本极高。还有人做过“缩放方案”——把整个 body 按比例缩放，这个方案在 iOS 上表现尚可，但在安卓上会遇到 WebView 的渲染精度问题，而且页面里的弹层、滚动、定位全部要跟着比例走，约束太多。

1.2 vw 方案的核心原理与直觉优势

vw 是 viewport width 的缩写，1vw 等于浏览器可视区宽度的百分之一。如果设计稿是 750 宽，那么 750px 就等于 100vw，1px 就等于 0.1333vw。postcss-px-to-viewport 干的事就是在构建时扫描所有 CSS 文件里的 px 值，按你配置的比例系数自动换算成 vw。

这个方案的本质，是把“单位换算”这件重复劳动全部前移到构建阶段。开发的时候你继续用设计稿上的原始 px 标注，不用心里换算，不用管屏幕宽度是多少，一切交给 PostCSS 插件处理。它没有 rem 方案的 JS 依赖，没有闪烁问题，不受系统字体大小影响，也不需要手写媒体查询，属于纯 CSS 层面的静态换算，干净利落。

1.3 为什么不是所有项目都适合这套方案

vw 方案有一个天然边界：它只对宽度方向上的适配友好，也就是水平方向的尺寸能用视口宽度等比缩放。但高度相关的属性如果也一律按 vw 换算，在极端屏幕比例（比如带鱼屏、折叠屏中间态）下会失真。比如一个按钮的高度，设计稿里是 80px，换成 vw 后，在不同屏幕比例的手机上高度会被拉得不一样，视觉上会显得很怪。

所以这套方案真正适合的是“内容型 H5 页面”——信息流、活动页、表单页、列表页，元素以横向排布为主，宽度变化是主要矛盾。如果是做后台管理系统、PC 端官网、或者对高度还原程度有极端要求的大屏可视化项目，建议继续用 px 加断点的方式，不要强行套 vw。

2. 安装与基础配置：怎么把插件接到现有构建流程里

这一节先讲最基础的接入动作，保证你能在本地把插件跑起来，然后再用一个最小配置解释它的工作方式。

2.1 安装依赖：包名与版本选择要点

安装命令很简单，先用 npm 装到开发依赖里：

npm install postcss-px-to-viewport --save-dev

如果你用的是 pnpm，把 npm 换成 pnpm 即可。版本方面需要注意的是，这个包的核心功能已经很稳定，几年都没怎么大改，所以不需要刻意追求最新版。我目前在用的是 1.1.1，各项行为都符合预期，没有升级刚需。装完确认一下 node_modules 里能正常解析这个包就行。

2.2 三种接入方式：Webpack、Vite、瘦身 PostCSS 配置

这个插件本质是 PostCSS 插件，所以只要你的构建流程里跑了 PostCSS，它就能接进去。最常见的三种场景我分别列一下。

场景一：Webpack 项目，如果你用的是 vue-cli 或者基于 webpack 的自建工程，找到 postcss.config.js 文件，加入插件即可：

module.exports = { plugins: { 'postcss-px-to-viewport': { viewportWidth: 750, }, }, };

场景二：Vite 项目，Vite 内置了 PostCSS 支持，在项目根目录同样放置 postcss.config.js，写法完全一样。需要注意的是 Vite 要求 PostCSS 插件必须使用具名导出或 CommonJS 兼容写法，上面这种对象式写法是可以正常识别的。

场景三：直接在 CSS 文件里手动建 PostCSS 管道，如果你在做 css-in-js 的库开发或者独立样式构建，可以在脚本里这样跑：

const postcss = require('postcss'); const pxtoviewport = require('postcss-px-to-viewport'); postcss([ pxtoviewport({ viewportWidth: 750, }), ]) .process(cssContent, { from: undefined }) .then((result) => { console.log(result.css); });

2.3 最小配置示例：理解输出的关键

配置里第一个必填项就是 viewportWidth，它的值应该等于你的设计稿宽度。我的项目拿到的视觉稿是 750 宽，所以这一项配置为 750。如果你用的是 375 宽的设计稿，就填 375。这个值决定了 px 和 vw 之间的换算比例——750 的稿子里 75px = 10vw，375 的稿子里 75px = 20vw，等比例关系。

跑一次构建后，样式输出的变化非常直观。比如写了一个按钮的样式：

/* 源码 */ .btn { width: 200px; height: 80px; margin: 20px auto; font-size: 28px; }

经过插件转换后变成：

/* 输出 */ .btn { width: 26.667vw; height: 10.667vw; margin: 2.667vw auto; font-size: 3.733vw; }

从这个输出结果可以看出，插件默认会把所有能换算的 px 全部转成 vw，包括宽度、高度、内外边距、字号，甚至边框宽度。如果你不想让某些属性被转化，就得靠后面的配置项来约束。

3. 不满足于默认行为：核心配置项逐个拆解

只配置一个 viewportWidth 能跑通，但远谈不上“完全指南”。这一节把常用配置项全部过一遍，并解释每个配置背后的取舍逻辑。

3.1 关键配置项一览表

先给一张速查表，方便你对照排查问题：

3.2 viewportWidth 取值：遇到 750 和 375 混合设计稿怎么办

规范统一的设计团队会固定用同一套设计稿宽度，但实际工作中，设计师有时会给 750 的移动端稿，隔一段时间又给一套 375 的稿。这时候你会很头疼——viewportWidth 只能填一个值，换稿子就得改配置。

我的处理方式是这样的：在 postcss.config.js 里用环境变量区分，比如默认按 375 构建，需要 750 稿的页面时单独在文件顶部加一段注释声明，再用一个自定义的 PostCSS 插件去识别这个标记并动态覆盖配置。这里不展开自定义插件的写法了，思路是优先保证团队内部设计稿宽度统一，因为多宽度混用会让产物不可预测，属于自找麻烦。

3.3 propList 与 selectorBlackList：精确控制哪些样式不应该被转

propList 默认是 ['*']，表示所有属性都参与转换。这个默认值看起来很省心，但实际项目里有一个高频问题：不希望字体大小跟随视口缩放。比如视觉稿里的标题字号是 40px，如果转成 vw，在 320px 的屏幕上字号只有 17.06px，在 414px 的屏幕上高达 22.08px。字体大小跨屏浮动太大，会造成标题换行不稳定，看起来也怪。

我推荐把 font-size 排除在转换范围之外，写法是用感叹号前缀做黑名单：

propList: ['*', '!font-size'],

注意这个感叹号语法，表示从默认全量中剔除。配合我上表里的推荐值，字体还是会用 px 写，等到真正需要大屏适配的时候，再单独用 clamp 或者媒体查询去微调，比一刀切转 vw 可控得多。

再看 selectorBlackList，它的作用是按选择器名称跳过转换。这个非常实用，因为第三方 UI 库经常有自己的样式覆盖机制，比如某些弹层组件内部用了固定定位，宽度不适合随视口缩放。在全局样式里把这些类名列进黑名单：

selectorBlackList: ['.ignore-', 'no-adapt'],

注意这里支持字符串匹配和正则匹配，字符串匹配是“包含即命中”，所以一个类名叫 .ignore-width 也会被命中。如果你只想精确匹配，用正则：

selectorBlackList: [/^\.ignore-/, /no-adapt$/],

我自己会在写组件时给“不要自适应”的根节点加一个ignore类名，省得反复改配置。

3.4 minPixelValue 与媒体查询、横屏配置的坑

minPixelValue 的默认值是 1，含义是小于等于 1px 的不转。这个设计是为了保住 1px 边框或多倍屏的细线效果。如果你把它改成 0，那么 border: 1px 会变成 border: 0.133vw，在部分安卓低端机上可能直接消失或变得很淡。所以这个默认值建议不要动。

mediaQuery 默认是 false，不转换 @media 里的 px。假如你的媒体查询里写了 min-width: 768px，因为媒体查询是基于视口的，把它转成 min-width: 102.4vw 在 iOS 上表现还行，但在某些安卓 WebView 里媒体查询的 vw 解析会有兼容问题。我的建议是把 mediaQuery 继续保持 false，媒体查询里手写像素断点，逻辑直观且不依赖插件。

landscape 横屏适配则是很多人会忽略的。配置为 true 后，插件会额外生成一组横屏样式，通过 @media screen and (orientation: landscape) 包一层，并按 landscapeWidth 重新计算。缺点就是产物体积会增加不少，如果你没有明确强需求，先关掉更理性。

4. 实战接入：三端方案落地记录（Vite + Vue + 第三方组件库）

配置原理讲完，这节给你一个可复制的完整接入过程，按真实项目的顺序来。

4.1 第一步：统一设计稿宽度与开发规范

项目接入前我先做了一件事：把团队的设计稿规范统一为 750 宽。这一步看起来和插件配置无关，实际上决定了整个适配方案的稳定性。750 是很多移动端设计团队的默认画板尺寸，以它为基准，iPhone 12 Pro Max 的 428 物理像素大约等于设计稿的 57%，iPhone SE 的 375 大约等于 50%，视觉缩放关系一目了然。

开发规范里我明确了几条硬性规则：边框一律用 1px 或 0.5px，不写 2px；字体大小不用 vw；内边距尽量使用 8 的倍数，减少小数换算造成的像素偏移。团队里新来的同事照着这份规范写，样式基本一次过。

4.2 第二步：在 Vite 项目里配置 postcss.config.js

我用一个 Vite + Vue 3 的项目做示例，根目录创建 postcss.config.js：

module.exports = { plugins: { 'postcss-px-to-viewport': { unitToConvert: 'px', viewportWidth: 750, unitPrecision: 5, propList: ['*', '!font-size'], viewportUnit: 'vw', fontViewportUnit: 'vw', selectorBlackList: ['.ignore-', 'no-adapt'], minPixelValue: 1, mediaQuery: false, exclude: [/node_modules/], include: [], landscape: false, }, }, };

注意这里我加了 exclude: [/node_modules/]。这个很关键，因为第三方组件库的样式如果也被转换，会和其内部自身的适配逻辑冲突。比如一些库已经内置了 rem 或自带媒体查询适配，你再把它转成 vw 会双重缩放，页面直接变大或变小。通常 vendor 样式建议原样打包，你自己开发的业务样式才参与转换。

4.3 第三方组件库尺寸不匹配：以 375 库配 750 稿为例

这是实战里踩得最深的一个坑，单独拿出来说。很多移动端组件库默认按 375 设计稿的尺寸来写样式，比如一个弹窗的宽度是 300px，他们的弹窗在每个屏幕上会占固定比例，不会溢出。但你的页面视觉稿是 750 宽的，页面其他元素转 vw 后可能和弹窗不成比例。

解决方式我试过两种。第一种是把 node_modules 里的样式也一起包含进转换，然后在配置里把 viewportWidth 改成 375，这样第三方库的 300px 会按 375 基准确认，而你的业务代码因为设计稿是 750，需要自己在源文件里把所有尺寸除以 2。这种写法很别扭，等于要让所有业务代码适配一个“中间标准”。

第二种更靠谱：node_modules 排除转换，第三方组件库保持它自己的原始 px 样式。同时将弹窗这类关键组件的样式通过全局覆盖的方式，用自己写的 vw 值替换掉它的 px。代价是工作量稍微增加，但效果最可控，也不用担心库升级后样式被破坏。我目前线上项目就是这种做法。

4.4 转完之后怎么看产物：源映射与调试技巧

转换后你会发现，浏览器 DevTools 里看到的是 vw 值，排样式的时候很难对应到源文件的 px。这里需要两个技巧：第一，开启构建工具的 css sourceMap，这样 DevTools 里能直接跳转到源 scss/less 文件，并能看到原始代码；第二，如果你在调试时需要临时验证某个 px 换算是否正确，直接在 DevTools 的样式中临时把 vw 改成 px，浏览器会实时响应，不需要改源文件。

Vite 里默认生产构建不生成 sourceMap，需要你在 vite.config.js 里显式开启：

export default defineConfig({ build: { cssSourcemap: true, }, });

注意这个选项只对 CSS 的 sourceMap 生效，开启后 DevTools 的样式来源会准确得多，排错效率提升一个档次。

5. 踩坑实录：文档里不会告诉你的五个真实问题

接入跑顺只是开始，真正耗费时间的是处理各种边界场景。这五个问题都是我实际遇到过并有解决方案的。

5.1 内联样式和动态样式不在转换范围内

postcss-px-to-viewport 只处理编译后的 CSS 文件，它不会碰你写在 HTML 里的 style 属性，不会碰 JS 里动态拼接的 px 字符串，也不会碰 Vue 模板里:style="{ width: '100px' }"这种写法。

这个问题的规避思路是：动态尺寸尽量用百分比或者 flex 布局实现；确实需要固定像素的内联样式，直接写 vw 值。举个实际例子，我的项目里有一个跟随手指移动的气泡提示，需要在 JS 里根据触摸位置设置 left 和 top，这里就不能依赖插件转换，我在源码里直接写：

element.style.left = `${Math.round(100 * xRatio)}vw`; // 手动换算

要注意动态算出来的 vw 在高刷新率屏幕上不会有明显区别，但保留两位小数比较稳妥。

5.2 background 简写里的 px 会被转换导致定位偏移

用 background 简写的时候，比如：

.box { background: url('icon.png') no-repeat 20px 30px; }

这里的 20px 和 30px 会被转换成 vw，但你的背景图实际尺寸可能并没有跟着设计稿等比缩放，最终呈现出来的背景图位置就是错的。更隐蔽的情况是background-size: 20px 30px和border-radius: 999px这种——前者如果转成 vw 可能让原本固定比例的背景图被拉扁拉长，后者还有救，因为 999px 转成 vw 在很多屏幕上接近一个很大的百分比，视觉上依然是圆角很圆的矩形，但严格来说还是变了。

处理策略：在写这类样式时给容器加上黑名单类名，或者拆开写属性避免被误转。例如背景定位改写成：

.box { background: url('icon.png') no-repeat; background-position-x: 20px; background-position-y: 30px; }

注意 background-position-x/y 不会被插件默认转换吗？答案是有可能，属性在 propList 默认全量的范围内。所以最稳妥的还是独立类名加黑名单，或者用 CSS 变量包裹不被转换的原始值。

5.3 地图、Canvas 和第三方 JS 渲染的尺寸不参与 CSS 转换

如果你的项目里有地图组件（比如某些 Web GIS 库）或者 Canvas 画布，它们的尺寸通常由 JavaScript 根据容器计算并写入像素值，CSS 转换对它们不起作用。地图的 marker 大小、Canvas 里的绘制坐标全部需要单独适配。

我的做法是写了一个工具函数，基于一个全局的“窗口宽度 / 设计稿宽度”比例去换算 JS 侧的像素值：

export const vw = (px, designWidth = 750) => { const clientWidth = window.document.documentElement.clientWidth; return parseFloat(((px * clientWidth) / designWidth).toFixed(2)); };

但这个函数有个注意点：只能在组件挂载后调用，因为需要真实视口宽度。如果是 SSR 环境，记得在 mounted 里执行而不是 setup 顶层。

5.4 字号排除后带来的两套单位混用问题

把 font-size 排除转换之后，页面里就同时存在 px 字号和 vw 尺寸的两套单位体系了。初期很容易出问题：一个容器宽高转成 vw，内部的文字行高、内边距又是 px，在极端屏幕比例下文字可能溢出盒子。

我后来总结了一条经验：排除 font-size 不是让你完全不考虑比例，而是把字号的适配从“全局等比缩放”改成“阈值内自动缩放，阈值外媒体查询修正”。具体做法是给全局设置一套基础字号变量，在不同断点下微调：

:root { --font-size-base: 28px; --font-size-title: 36px; } @media (max-width: 350px) { :root { --font-size-base: 26px; --font-size-title: 34px; } }

这样既避免了字号在极端屏下过大过小，又保留了整体缩放带来的线条一致性。

5.5 横屏适配与安全区：viewport 方案在 iPhone 上的遗留问题

vw 方案对 iPhone 的刘海屏并不友好，因为视口宽度不包含安全区。当你用 vw 布局后，横屏状态下左右两侧被刘海和圆角遮挡的概率很高。竖屏时底部 home indicator 也容易和操作按钮重叠。

我最终采用双保险：postcss-px-to-viewport 负责常规单位换算，同时额外在全局样式里引入 env(safe-area-inset-*) 修复安全区。比如给底部操作栏加：

.safe-bottom { padding-bottom: constant(safe-area-inset-bottom); padding-bottom: env(safe-area-inset-bottom); }

有些文章提到加 viewport-fit=cover 和 viewport-units-buggyfix 来修补兼容性。viewport-fit 确实需要在 HTML 的 meta 标签里声明，如果你不做 iPad 横屏适配，可以暂时不管；viewport-units-buggyfix 这个库通过给 vw 生成辅助的 vh 单位，解决老安卓 WebView 对 vw 支持不完整的问题，但我实测在近三年的手机浏览器上已经没有兼容性故障，所以这个库我没有引入到线上，如果你要兼容 iOS 12 之前的系统，可以自己评估是否需要。

6. 适配方案的进阶玩法：优化产物与合作限制

基础跑通之后的优化方向同样重要，这一节说几个能拉开团队整体效率的做法。

6.1 配合 CSS 变量实现“局部不缩放”

有些场景需要局部不缩放——比如价格数字要绝对清晰，比如某些图标希望物理尺寸恒定。以前只能靠黑名单类名手动标记，但标记多了之后类名很乱。我这里提供一种更优雅的做法：利用 CSS 自定义属性把需要固定的值存起来，在关键节点覆盖。

不缩放区域的结构长这样：

<div class="price-ignore"> <span class="amount">￥99.99</span> </div>

样式可以这样写：

.price-ignore .amount { font-size: 20px; letter-spacing: 0.5px; }

然后通过在全局适配合入类：

.ignore-keep { /* 借由插件的黑名单类名，保证这里的样式完全不参与 vw 转换 */ }

这段看起来简单，但它的意义在于：团队约定只要组件根节点包含.ignore-前缀，整个子树都豁免适配，代码 review 时一眼就能看到这一片的“例外”没有被插件误伤，比事后调配置可读性好得多。

6.2 大屏适配策略：要不要给 vw 设个上限

vw 是相对视口宽度等比缩放，如果你做的是手机 H5，在平板或者折叠屏大屏打开时，元素会被放大到失去比例。常见的做法是给根容器设置一个最大宽度，比如 540px 或 600px，居中展示，让页面左右留白。

这里有另一个思路：max-width 用 px 固定，内部的元素继续按 vw 走，这样在大屏上页面整体不再被拉宽，而是核心内容区域自适配。比如：

.page { max-width: 600px; margin: 0 auto; }

但注意 max-width 本身会被插件转换吗？如果它写在你的业务 CSS 里，会被转换成 vw，这样在大屏上还是会被拉宽。所以这条样式你需要放到黑名单类的范围内：

.ignore-app-shell { max-width: 600px; margin: 0 auto; }

然后页面根节点套上这个类名。这是一个很妙的折中：有限大屏内继续 vw 缩放，超过上限后视觉不无脑放大。

6.3 回到本质：什么时候你应该放弃这个方案

这个方案不是银弹，如果你遇到下面这些情况，建议考虑换方案：

第一，项目主要面向 iPad、折叠加桌面端浏览，视口宽度本来就是自由伸缩的，vw 等比缩放反而限制内容阅读性，更适合用 clamp 和流式布局。第二，设计团队要求严格还原 iOS 原生控件的视觉规范，比例自适应会让尺寸不可控。第三，项目里有大量 js 动态绘制的图表和复杂 canvas 场景，转换收益很低，反而带来无尽的 JS 侧换算工作。

我在另一个可视化大屏项目里就没有用它，改用了一套基于 rem 的专属比例适配，因为那个场景下高度和宽度同时参与等比缩放，vw 单维度无法满足需求。

6.4 团队规范与自动化校验：防止“漏配”修复回归

最后分享一个团队落地层面的经验。配置好插件只是起点，总有人会直接在内联样式里写 px、有人会用奇奇怪怪的单位 mixin，有人会在 scss 里偷偷写死媒体查询。

建议在 CI 流程里加一个简单的样式扫描脚本——检查产物 CSS 文件里是否还有超过阈值的 px 单位。这个脚本不需要很复杂，正则扫一下排除黑名单类就行，重点是把“适配规则可执行化”。我现在的项目就配了一个小时级的自动检查任务，一旦发版产物里出现某些文件大量残留 px，就直接标记一个 lower priority 的 issue 给提交者。

这样一个工具链组合下来，人工 review 的工作量减少许多，团队新成员也不会因为不懂适配而产出“异形页面”。

7. 一段真实的收尾体会

从最初在 rem 里调字体大小，到现在构建阶段一键转 vw，这套方案给我最大的收获不是代码数字的变化，而是让团队重新把注意力放回了视觉稿本身。设计师交付 750 的稿子，前端就老老实实按 750 写 px，不存在谁迁就谁的问题，也不存在上线前临时修一堆“机型差异”的紧急补丁。

如果你正准备接入 postcss-px-to-viewport，我的建议是先小范围试点一个页面，跑完看产物，观察线上真机表现，再决定是否铺开到全项目。插件的默认行为往往不是你的最终答案，按我上面说的配置项逐项过一遍，重点想清楚 font-size 到底要不要转、node_modules 要不要排除、媒体查询要不要处理，这三个问题想明白了，你的适配体系就已经成型一大半了。