企业官网建设流程全解析

做移动端H5适配，绕不开那个经典问题：设计稿750px宽，真机却是375px甚至更窄。以前我为了这个折腾过手写媒体查询、rem换算、flexible.js动态改根字号，后来接触到postcss-px-to-viewport，才真正觉得“构建时解决适配”这件事变得干净了。它做的事情很简单：在编译CSS的时候，把所有px自动按比例换算成vw，你写代码还是按设计稿的px来写，出来的效果却能在不同宽度屏幕上等比缩放。

这篇东西我会从方案选型讲起，把配置项一个个拆开，再给Vite和Webpack的接法，最后聊聊我在真实项目里踩过的坑，比如第三方UI库、1px边框、内联样式、calc表达式这些。适合刚接触移动端适配的开发者，也适合已经在用但被各种怪问题卡住的人。

1. 为什么我推荐vw方案：px自动换算的底层思路

1.1 从“写死px”到“换算出vw”：这个插件到底在做什么

PostCSS本身是一个用JS解析CSS的工具，它把CSS解析成抽象语法树，插件就在这棵树上做修改。postcss-px-to-viewport就是其中一个插件，它在扫描到px单位时，会套用这样一个公式：

vw = (px / viewportWidth) * 100

比如设计稿宽度是750px，按钮宽度300px，转换后就是(300 / 750) * 100 = 40vw。在375px宽的手机上，40vw等于150px，正好是设计稿宽度的40%，和你在设计稿上看到的视觉比例完全一致。这里的关键是“比例”两个字。用vw写的界面，不管屏幕多宽，每个元素占视口的比例都和设计稿一致，这就是等比缩放。如果你用固定px，在750设计稿上写300px的按钮，到了375的屏幕上依然是300px，按钮占了整个屏的80%，视觉就完全变了。

我习惯打一个比方：设计稿是一张照片，vw方案就是让照片始终按屏幕宽度等比缩放显示，不管放大到多大，照片里的构图比例不变。你的代码里不需要写任何媒体查询，也不需要JS参与，构建期就把适配做完了。这也是这个插件最吸引我的地方——开发者日常写px，构建产物自动变成vw，几乎无感知。

1.2 对比rem、媒体查询和百分比：为什么最终选了vw

适配方案不是只有vw一种，我早年也试过很多：

媒体查询确实能做适配，但宽度变化大的时候，手写断点下的整套样式成本很高，字体、间距、布局都要重新适配，多写几套基本就是灾难。百分比方案有个问题：width百分比相对父容器，padding和margin相对父容器宽度，height百分比却相对父容器高度，语义不一致，而且字体缩放根本没法用百分比解决。

rem加flexible这套组合曾经很流行，需要动态计算html的font-size，依赖一段JS运行时脚本。rem本身并不直观，还要考虑dpr的适配，构建完还得挂脚本，多一层运行时负担。vw是浏览器原生支持的视口单位，没有中间层，不需要JS，构建完就完事，这是它最大的优势。唯一要权衡的是兼容性，iOS 8+、Android 4.4+基本覆盖了现代移动端，项目只要不要求特别老的机器，完全够用。

另外它比postcss-pxtorem省心的地方在于：pxtorem要配合动态根字号来用，根字号一改，所有rem比例都变；vw直接基于视口宽度，不需要全局改任何变量。所以我在新项目里，只要确定是纯移动端场景，基本无脑选vw方案。

1.3 什么样子的项目适合用，什么项目建议别碰

我自己用下来的感受：适合的活动页、H5商城、跨端WebView页面，这些场景宽度相对可控，追求视觉和设计稿1:1。不适合的是PC后台管理、复杂数据表格、富文本长文阅读——这类页面需要固定列宽和阅读宽度，vw一缩就乱了。如果你的项目是PC和移动端共用一套代码，PC端宽度远超设计稿，我建议不要全局启用这个插件，要么单独拆分移动端页面，要么用其他适配方案。

这一点一定要在选型阶段想清楚。我见过一个后台项目强行上了px转vw，结果数据表格每列宽度都跟着屏幕飘，大屏上列间距大得离谱，最后全部类名加黑名单返工，非常痛苦。插件本身没有错，但用错了场景就是灾难。

2. 安装与基础配置：一套配置跑通750设计稿

2.1 安装与PostCSS环境准备

装包很简单：

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

这个包依赖PostCSS 8，工程里已经有PostCSS的话装完直接配置即可。如果你的项目比较老还在PostCSS 7，可能需要升级PostCSS，或者找兼容老版本的fork分支。我一般在Node 16+的环境里跑，没有遇到过什么问题。

有一点要注意：如果项目的package.json里设置了"type": "module"，那么postcss.config.js会被当成ESM执行，里面如果再写module.exports会直接报错。解决办法是把配置文件重命名为postcss.config.cjs，或者改成export default的写法。这个报错信息不太友好，我第一次遇到时排查了很久。

2.2 配置项逐个拆解

这个插件的配置项不算多，但每个都值得认真看一遍：

viewportWidth是使用频率最高的参数。750设计稿下，px转出来的vw在375屏正好是一半，比较符合直觉；375设计稿下，px转出来的vw在375屏就是1:1，同样符合直觉。选哪个主要看团队的设计规范，没有绝对的对错，但一定要统一下来。

propList支持通配符和取反，比如['*', '!border']表示除border外全部转换。我常用的写法是['*', '!letter-spacing', '!border']，因为字间距和边框这类细节，转了以后小数点误差影响视觉。selectorBlackList则适合匹配特定类名或正则，比如.ignore-px、/^\.hairline/，命中的选择器不转换。

replace设为false算是一个隐藏的降级方案。同一个声明会同时输出px和vw，老浏览器读到px就用px，支持vw的浏览器用后面的vw覆盖。不过现在兼容性问题已经很小了，我自己基本用默认的true。

exclude和include是一对需要小心的配置，都是正则匹配文件路径。我踩过的一个坑是：exclude的优先级高于include，换句话说某个文件如果同时命中exclude和include，最终会被排除。这个行为很容易理解错，配置之前最好先仔细读一遍源码的逻辑思路。

2.3 一套可直接复制的配置模板

直接给一个我常用的配置模板：

module.exports = { plugins: { 'postcss-px-to-viewport': { viewportWidth: 750, unitPrecision: 5, propList: ['*', '!letter-spacing', '!border'], selectorBlackList: ['.ignore-px', '.hairline'], minPixelValue: 1, mediaQuery: false, exclude: [/node_modules/], landscape: false } } };

这个模板的设计逻辑：750设计稿，排除字间距和border的转换，保留1px边框，带ignore-px和hairline类名的模块不参与转换，先不管node_modules里的第三方库。如果你用的是375设计稿，把viewportWidth改成375，exclude按实际需要保留或去掉就好。

有人会问为什么排除border。因为边框的1px转成0.133333vw后，在375屏上等于0.5px，很多浏览器不渲染这么细的线，视觉上边框直接消失。这种细节不提前处理，测试阶段会被反复打回。

3. 实战接入：Vite和Webpack项目里的配置姿势

3.1 Vite项目接入：最省事的路径

Vite天生支持PostCSS，直接在vite.config.js的css.postcss里配就行。示例：

import postcssPxToViewport from 'postcss-px-to-viewport'; export default defineConfig({ css: { postcss: { plugins: [ postcssPxToViewport({ viewportWidth: 750, unitPrecision: 5, propList: ['*', '!letter-spacing', '!border'], selectorBlackList: ['.ignore-px', '.hairline'], minPixelValue: 1, mediaQuery: false, exclude: [/node_modules/] }) ] } } });

也可以把配置放到postcss.config.js里，Vite会自动读取。但这里有个容易忽略的规则：如果同时写了vite.config里的css.postcss和项目根目录的postcss.config.js，Vite会优先使用vite.config里的配置，另一个会被完全忽略。我在项目里吃过这个亏，改了postcss.config.js半天没反应，最后才发现是vite.config里的旧配置在生效。建议团队统一一处配置位置，别两处都写。

3.2 Webpack项目接入：loader顺序别搞反

Webpack需要postcss-loader，常见规则：

module.exports = { module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader', 'postcss-loader'] }, { test: /\.scss$/, use: ['style-loader', 'css-loader', 'postcss-loader', 'sass-loader'] } ] } };

执行顺序是从右往左：scss先被sass-loader编成css，然后postcss-loader执行px转vw，再交给css-loader和style-loader。如果把postcss-loader放在sass-loader前面，遇到sass语法就会直接解析失败，这个顺序问题新人很容易踩。

postcss-loader版本不同，配置写法也不同。loader 8.x之后，插件的配置放在postcssOptions里：

{ loader: 'postcss-loader', options: { postcssOptions: { plugins: [ ['postcss-px-to-viewport', { ... }] ] } } }

老版本则是：

{ loader: 'postcss-loader', options: { plugins: () => [ require('postcss-px-to-viewport')({ ... }) ] } }

同一个项目里最好统一loader版本，不然不同人拉下来的分支跑起来配置报错会很烦。检查报错时先看postcss-loader版本，再对照配置格式，能省不少排查时间。

3.3 Vue/React 单文件组件样式：其实不用额外配置

Vue单文件组件里的style，vue-loader会把它提取出来交给postcss-loader，所以只要postcss-loader配置好了，class里的px一样会被转换。scoped属性只是在选择器上加hash，不影响px转换。React项目用CSS Modules同理，配置一次全局生效。

所以现实场景里，项目样式代码写起来和以前完全一样，不用手动写vw，唯一要做的是在样式规范里约定：尺寸、间距、字号都按设计稿px写，插件会在构建期自动处理。团队里一个新同学半天就能上手，几乎不用额外讲解适配逻辑。这也是我推荐这个插件的原因之一，降低团队协作成本比技术本身更重要。

4. 常见问题与排查技巧：第三方库、1px边框和内联样式

4.1 第三方组件库：为什么转换后UI全乱了

前面提到exclude: [/node_modules/]，这个配置会导致第三方UI库的px不被转换。如果你的UI库是按375设计稿写的，而项目用的是750设计稿，保留UI库的px在375屏上反而能对上，因为375屏正好是750的一半。但如果你项目用的是375设计稿，UI库的px不转也正好对，问题在于项目其他样式转了，在大屏上项目样式等比放大而UI库不变，比例就会乱。

举个例子：UI库的按钮在375设计稿上是200px，你的设计稿是750，你在页面上也画了一个按钮300px，期望视觉上两个按钮一样宽。你的300px转成40vw在375屏等于150px，UI库的200px保留px在375屏还是200px，两者就对不上了。

我的处理原则是：先确认UI库的设计稿基准，再决定是否排除。如果UI库样式和项目样式基准不一致，最省事的做法是让UI库也走转换，但它内部的px如果也是按375写的，就要用include精确指定路径，只转换需要的组件包。很多UI库官方文档里也有适配方案，优先看文档，别自己瞎折腾。

4.2 1px边框和hairline问题

CSS的1px在物理屏幕上可能对应2px甚至3px，看起来偏粗。很多方案是转成0.5px，但兼容性参差不齐。我的做法是：minPixelValue设为1，保证普通的1px边框不被转成vw；需要hairline效果的模块，类名直接加进selectorBlackList，然后用伪元素的transform: scale(0.5)方案实现。

项目样式规范里我会写清楚：带hairline类的边框不做vw适配，统一走物理像素方案。这样才能保证不会出现有的地方边框细、有的地方边框粗的混乱情况。如果没有这个约定，测试测出一堆边框粗细不一的问题，改起来其实很费劲。

4.3 内联样式里的px：PostCSS管不了

这是最容易忽视的坑。PostCSS只能处理CSS文件或style标签里的样式，组件代码里style={{ width: '100px' }}，或者HTML标签的style属性，它一概不管。这些px会原样带到浏览器，在375屏上显示成100px，完全不参与适配。

我踩过之后定了一条规矩：项目里不允许直接写内联样式尺寸，所有尺寸一律走class，规则靠代码review和lint约束。如果你接手的是存量项目，内联px除了一条条抽成class，没有捷径。除非你有精力去搞CSS-in-JS的编译期转换，否则这个坑只能靠规范填。

4.4 大屏上vw无限放大：页面太宽怎么办

vw是相对视口的，PC屏幕1024px宽，元素40vw就是410px，视觉比例没错但整体偏大。这个问题本质上是vw方案不适合PC。如果只是移动端页面偶尔被拉到PC上看，可以给body或根容器设置max-width，再通过媒体查询在大屏上做一点修正。但如果你要做的本来就是PC后台，真的不建议用这个插件，选型阶段就要避开。

还有一种取巧的办法是把整个应用包在一个width: 100vw的容器里，用transform: scale按目标宽度缩放。我试过一次就放弃了，滚动条、定位、交互都会出现各种怪问题，工程上维护成本极高。这类hack方案看起来简单，实际上坑比效果多，不推荐。

4.5 字体也跟着缩放：阅读体验怎么保证

vw等比缩放下，字体也会跟着屏幕放大缩小。活动页问题不大，但文章正文如果跟着变大，阅读体验会打折扣。解决方式有几种：在propList里把font-size排除掉，例如['*', '!font-size']；或者只用vw控制标题，正文用固定px配合媒体查询微调。

我的习惯是：标题、按钮、卡片这些装饰性文字用vw没问题，正文至少保留一个正常字号底线，别在大屏上变成巨型字。另一种思路是设置html的font-size基准，正文用rem，这种混排方案在复杂内容项目里更实用。插件不强迫你全转，propList就是给你留口子的，按场景取舍就好。

5. 进阶配置与实战避坑：横屏、Tailwind和那些隐形坑

5.1 横屏适配：让页面在横屏下也按比例走

移动端横屏时，视口宽度变成原来的高度，按竖屏设计稿转出的vw在横屏下比例会失调。插件提供了landscape配置，开启后会在转换结果里追加一段@media (orientation: landscape)的规则，配合landscapeWidth重新计算。这里要注意的是：开启后生成的CSS体积会明显变大，因为同样的样式要输出两套。我建议在确实需要横屏场景的业务页里再开，平时没必要。

5.2 搭配Tailwind或CSS变量：一些额外的观察

如果项目里用了Tailwind，要特别小心。Tailwind的间距体系默认基于rem，不是px，插件只管px，所以大部分工具类不会受影响。但自定义任意值比如w-[100px]、border这类还是会产生px，preflight里也有不少边界样式，全局启用后可能会被转成vw，出现意料之外的缩放。我的建议是：Tailwind项目不要全局开px转vw，如果某个业务模块必须要，把样式单独抽出来，用include精确控制，或者干脆用Tailwind内置的vw工具类。

CSS变量在vw方案下也可以配合使用，比如把主题色间距定义成变量，变量里写px。实测中变量内部的px一般不转换，所以推荐：变量只存数值，具体单位在属性里写px，让插件统一处理，这样可控性更高。

5.3 我踩过的一些隐形坑

• calc表达式里的px会被转换。例如calc(100% - 30px)产出calc(100% - 4vw)，在375屏上等于100%-15px，看起来合理，但如果calc里还有括号和多个单位混算，转换后可能出现你完全没想到的结果。所以calc里能不用px就不用px，或者干脆抽成CSS变量。
• unitPrecision不要设太小。vw值经常是0.133333vw这种长小数，精度设成2，多个值相加就会产生1px误差。我一直在用5。
• box-sizing必须全局统一成border-box。vw转换后宽度都是浮动的，如果有的元素是border-box、有的是content-box，换算结果会差出边框宽度，出现对不齐的现象。
• 转换产物一定要在真机或DevTools设备模拟里看一遍。我在一个项目里因为image的max-width用了100%没转，而它的父级宽度转了，导致图片在小屏上溢出。很多问题不是插件本身，而是“你以为转了其实没转”。

这些坑我基本都在项目里遇到过，写出来给你排雷。如果后面再碰到别的，我再来补充。

我个人在实际项目里的习惯是：750设计稿为主，UI库按基准单独处理，1px边框用hairline类名排除，字号按场景决定是否参与转换。遇到内联样式px，就繁琐一点抽成class。这套组合拳经过几个移动端项目验证，效果稳定。真要说建议的话，我建议你先拿一个真实页面做demo，跑一次构建，打开产物看看哪些px没转、哪些被意外转了，确认符合预期再全面铺开。适配方案没有银弹，每个项目的边界都不一样，多跑几个页面，你会慢慢找到最适合自己的配置。最后再分享一个小技巧：配置好的postcss文件记得提交到仓库，团队其他人拉下来就能用，不管谁接手都能保证同样的适配效果。