viewportWidth必须严格等于设计稿画布宽度（如750px或375px），minPixelValue应设为2以保留1px边框；propList需显式声明布局属性，selectorBlackList配合类名忽略非缩放样式，exclude排除node_modules。
必须配对设计稿宽度，否则所有 vw 值整体偏移——这是绝大多数项目出问题的根源。
viewportWidth 必须严格等于设计稿画布宽度
这个值不是设备物理宽度，也不是浏览器 window.innerWidth，而是 UI 给你的 PSD/Sketch 文件的画布宽度。常见两种情况：
- UI 提供的是
750px切图（2x 图）→ 配viewportWidth: 750 - UI 提供的是
375px预览稿（1x 图）→ 配viewportWidth: 375 - 团队混用两种稿？必须统一，插件不会“智能识别”，配错会导致转换结果缩放一倍（例如 100px → 26.66667vw 而非 13.33333vw）
propList 和 selectorBlackList 要协同控制转换范围
默认 propList: ['*'] 看似省事，但实际会把不该转的也转了：
-
border: 1px solid #ccc→ 变成约0.26667vw，在大屏上几乎不可见 - 第三方库（如
element-plus、vant）样式被误转，布局错乱 -
transform: translateX(20px)这类动画硬编码值不该参与视口缩放
推荐做法：
立即学习“前端免费学习笔记（深入）”；
- 显式声明常用布局属性：
propList: ['font-size', 'width', 'height', 'padding', 'margin', 'max-width', 'min-width'] - 给需保留 px 的元素加类名，如
class="ignore-px"，再配selectorBlackList: ['ignore-px'] - 整个
node_modules目录建议忽略：exclude: [/node_modules/]（需插件支持，postcss-px-to-viewport-8-plugin可用）
minPixelValue 和 unitPrecision 决定 1px 边框和小数可读性
这两个参数直接影响移动端最典型的“1px 消失”问题和 CSS 体积：
-
minPixelValue: 2：所有 ≤2px 的值（含1px、2px）保持原样，不转为 vw -
unitPrecision: 3：避免14px → 3.7333333333333334vw这种超长小数；过低（如1）会导致3px和4px都变成1vw，间距塌陷 -
mediaQuery: true必须开启，否则@media (max-width: 768px)里的 px 不会转，断点逻辑失效
配置文件位置和基础结构要匹配构建链路
多数现代前端项目（Vue CLI、Vite、Webpack）默认读取 postcss.config.js，但注意：
- Vite 用户若用
vite-plugin-postcss，仍需该文件；部分模板可能用.postcssrc或package.json#postcss，优先确认构建工具文档 - 安装命令是：
npm install postcss-px-to-viewport --save-dev（注意不是postcss-px-viewport，后者是旧版或拼写错误） - 基础配置示例（非全量）：
module.exports = {
plugins: {
'postcss-px-to-viewport': {
viewportWidth: 750,
unitPrecision: 3,
propList: ['font-size', 'width', 'height', 'padding', 'margin'],
selectorBlackList: ['ignore-px'],
minPixelValue: 2,
mediaQuery: true,
exclude: [/node_modules/]
}
}
}
真正容易被忽略的是：viewportWidth 和设计稿的绑定关系，以及 minPixelValue 对 1px 边框的兜底作用——这两项一旦设错，调试时很难从生成的 CSS 里反推原因。
