PostcssPx 单位转换

@vital-design/postcss-px 是 uni-app 场景的 PostCSS 单位转换插件：H5 把 px 转 rem，小程序把 px 转 rpx，同一份样式无需维护两套单位。

• 换算基准对齐 uni-app 官方方案：设计稿 375、rootValue 16、rpx 倍率 750 / designWidth
• 支持 platform: 'auto'，按 UNI_PLATFORM 自动选择输出单位
• 会转换 var(--gap, 16px) 这类 CSS 变量回退值（含嵌套 var），跳过引号字符串与 url()
• propList / selectorBlackList / replace / mediaQuery / minPixelValue 等配置沿用 postcss-pxtorem 语义，便于已有项目平移

安装

TIP

组件包解压安装时，将 @vital-design/postcss-px 一并放入项目 node_modules/@vital-design/ 下（同 快速上手 的引入方式）。

在 Vite（uni-app）构建链中使用时无需单独安装 postcss：Vite 自带 postcss ^8 并负责调用插件，本插件运行时也不依赖 postcss 包（仅类型引用）。这与 Node 版本无关。只有脱离 Vite、独立跑 postcss 的工具链（如裸 postcss-cli）才需要自行 npm i -D postcss@^8.1.1。

快速开始

Vite（uni-app）

// vite.config.ts
import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';
import postcssPx from '@vital-design/postcss-px';

export default defineConfig({
  plugins: [uni()],
  css: {
    postcss: {
      plugins: [
        postcssPx({
          platform: 'auto',
          unitPrecision: 5,
          selectorBlackList: ['no-px'],
        }),
      ],
    },
  },
});

postcss.config.js

const postcssPx = require('@vital-design/postcss-px');

module.exports = {
  plugins: [
    postcssPx({ platform: 'auto' }),
  ],
};

转换效果

/* 输入 */
.a {
  width: 16px;
  font-size: 14px;
  padding: var(--gap, 16px);
  content: "16px";
  background: url(a-16px.png);
}

/* H5（platform: 'h5'） */
.a {
  width: 1rem;
  font-size: 0.875rem;
  padding: var(--gap, 1rem);
  content: "16px";
  background: url(a-16px.png);
}

/* 小程序（platform: 'mp'） */
.a {
  width: 32rpx;
  font-size: 28rpx;
  padding: var(--gap, 32rpx);
  content: "16px";
  background: url(a-16px.png);
}

换算规则

平台	输出单位（默认）	计算式	示例
h5	rem	px / rootValue	16px → 1rem（rootValue 16）
mp	rpx	px × (750 / designWidth)	16px → 32rpx（designWidth 375）

设计稿宽度不是 375 时，只需要改 designWidth：

postcssPx({ platform: 'mp', designWidth: 750 }); // 10px → 10rpx，倍率为 1

platform: 'auto' 读取 process.env.UNI_PLATFORM，等于 'h5' 时按 H5 处理，其余平台（含未设置该环境变量时）一律按小程序处理。需要强制行为时显式传 'h5' 或 'mp'。

属性 Options

import type { PostcssPxOptions } from '@vital-design/postcss-px';

参数	说明	类型	默认值
platform	输出单位所属平台；auto 读 UNI_PLATFORM	'h5' | 'mp' | 'auto'	'auto'
designWidth	设计稿宽度，驱动 rpx 倍率（750 / designWidth）	number	375
rootValue	rem 换算根值，对齐 uni-app H5（375 宽 = 16px）	number	16
unit	强制输出单位；不传时按平台取 rem / rpx	string	-
unitPrecision	结果小数位	number	5
propList	属性白名单，支持 *、*contain*、prefix*、*suffix，! 前缀取反	string[]	['*']
selectorBlackList	选择器黑名单，命中则整条声明不转换	(string | RegExp)[]	[]
replace	false 时保留原声明并在其后追加转换结果	boolean	true
mediaQuery	是否转换 @media 参数中的 px	boolean	false
minPixelValue	小于该值的 px 不转换	number	0
exclude	排除文件：子串、正则或判定函数	string | RegExp | ((filePath: string) => boolean) | null	null
transform	自定义换算，返回值直接拼接输出单位	(pixels: number) => number	见「换算规则」

propList 示例：

postcssPx({ propList: ['*', '!font-size', '*gap*'] }); // 除 font-size 外全部转换，font-size 之外的含 gap 属性也转换

replace: false 便于做渐进迁移，输出的两条声明若完全相同会自动去重：

/* { platform: 'mp', replace: false } */
.a {
  width: 16px;
  width: 32rpx;
}

已知边界

• 只识别小写 px（大写 PX 不转换），且必须是 数字 + px 形式；em、%、vw 等原样保留。
• 引号字符串（content: "16px"）与 url() 内部不做替换。
• 换算结果为 0 时输出 0 而不是 0rem / 0rpx。
• exclude 依赖 PostCSS 的文件路径（root.source.input.file），构建链未提供 from 时不会命中。

API 导出

import postcssPx, {
  resolveOptions,
  resolvePlatform,
  createDefaultTransform,
  DESIGN_WIDTH,        // 375
  ROOT_VALUE,          // 16
  RPX_DESIGN_WIDTH,    // 750
  RPX_RATIO,           // 2
} from '@vital-design/postcss-px';

resolveOptions / resolvePlatform / createDefaultTransform 可单独用于自定义构建脚本；类型导出包含 PostcssPxOptions、ResolvedPostcssPxOptions、Platform、ResolvedPlatform、ExcludeOption。