postcss-px-convert

postcss-px-convert

一个功能强大的 PostCSS 插件和 Node.js 工具，支持将 CSS 中的 px 单位转换为 rem 或 vw，适用于移动端响应式开发。

English | 中文文档

✨ 特性

• 🚀 高性能: 基于 PostCSS 生态，转换速度快
• 🎯 精确转换: 支持精确的数值计算和单位转换
• 🔧 灵活配置: 丰富的配置选项，满足各种需求
• 📱 移动端优化: 专为移动端响应式设计优化
• 🛠️ 多场景支持: 支持 CSS、JS、Vue、React 等多种项目
• 🔌 插件生态: 提供 PostCSS 插件和 Vite 插件
• 📦 自动生成: 支持自动生成和注入 flexible.js
• 🎨 过滤功能: 支持选择器、属性、文件等多种过滤方式
• 🔄 混合单位: 支持 vw 和 rem 混合使用，不同属性可使用不同单位

📦 安装

npm install postcss-px-convert --save-dev

或者使用 pnpm：

pnpm add postcss-px-convert --save-dev

或者使用 yarn：

yarn add postcss-px-convert --dev

🚀 快速开始

基础用法

rem 配置示例

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-convert': {
      unitToConvert: 'rem',
      rootValue: 37.5,      // 设计稿宽度的 1/10，375px 设计稿对应 37.5，750px 设计稿对应 75
      unitPrecision: 5,
      propList: ['*'],      // 所有属性都转换
      selectorBlackList: [], // 不需要转换的选择器
      replace: true,        // 转换后是否移除原来的 px
      mediaQuery: false,    // 媒体查询内的 px 是否转换
      minPixelValue: 1      // 小于等于 1px 的不转换
    }
  }
}

vw 配置示例

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-convert': {
      unitToConvert: 'vw',
      viewportWidth: 375,  // 设计稿宽度
      unitPrecision: 5,
      propList: ['*'],
      selectorBlackList: [],
      replace: true,
      mediaQuery: false,
      minPixelValue: 1
    }
  }
}

独立配置文件方式

// .postcssrc.js 或 postcss.config.js
module.exports = {
  plugins: {
    autoprefixer: {
      overrideBrowserslist: ["Android >= 4.1", "iOS >= 7.1", "Chrome > 31", "ff > 31", "ie >= 8"]
    },
    'postcss-px-convert': {
      unitToConvert: 'rem',
      rootValue: 37.5,
      unitPrecision: 5,
      propList: ["*"],
      selectorBlackList: ["ignore"],
      replace: true,
      mediaQuery: false,
      minPixelValue: 0,
      exclude: /node_modules/i
    }
  }
}

Vite 项目

// .postcssrc.js
export default {
	plugins: {
		autoprefixer: {
			overrideBrowserslist: ["Android >= 4.1", "iOS >= 7.1", "Chrome > 31", "ff > 31", "ie >= 8"],
			add: true,
			grid: false,
		},
		"postcss-px-convert": {
      unitToConvert: 'rem',
			rootValue: 78,
			unitPrecision: 5,
			propList: ["*"],
			selectorBlackList: ["ignore"],
			replace: true,
			mediaQuery: false,
			minPixelValue: 0,
			exclude: /node_modules/i,
      injectFlexibleScript: true,
		},
	},
};

// vite.config.js
import { defineConfig } from 'vite';
import postcssPxConvert from 'postcss-px-convert';
// rem 适配时，自动生成并引入 flexible.js
import { viteFlexibleInject } from 'postcss-px-convert';

export default defineConfig({
  css: {
    postcss: {
      plugins: [
        postcssPxConvert({
          unitToConvert: 'rem',
          rootValue: 37.5,
          injectFlexibleScript: true
        })
      ]
    }
  },
  plugins: [
    viteFlexibleInject()
  ]
});

vw + rem 混合配置示例

混合模式允许不同 CSS 属性使用不同的转换单位，实现更精细的响应式控制：

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-convert': {
      unitToConvert: 'rem',      // 默认单位（未在 unitMap 中配置的属性都使用此单位）
      rootValue: 37.5,           // rem 基准值
      viewportWidth: 375,        // vw 基准宽度
      unitMap: {
        'width': 'vw',           // 布局尺寸用 vw
        'height': 'vw',
        'font-*': 'rem',         // 字体相关用 rem
        'margin*': 'rem',        // 间距用 rem
        'padding*': 'rem',
      },
    }
  }
}

转换效果：

.container {
  width: 375px;        /* → 100vw (unitMap 指定) */
  height: 200px;       /* → 53.33vw (unitMap 指定) */
  font-size: 32px;     /* → 0.85rem (unitMap 指定) */
  margin: 20px;        /* → 0.53rem (unitMap 指定) */
  border-radius: 8px;  /* → 0.21rem (使用默认 unitToConvert: 'rem') */
}

特殊控制： 可通过注释临时覆盖单位配置：

.special {
  /* px-convert:vw */
  font-size: 32px;     /* 强制转为 vw，而非 unitMap 配置的 rem */
  
  /* px-convert:rem */
  width: 375px;        /* 强制转为 rem，而非 unitMap 配置的 vw */
}

现代 PostCSS 配置（数组格式）

// postcss.config.js
import postcssPresetEnv from "postcss-preset-env";
import postcssPxConvert from "postcss-px-convert";

export default {
  plugins: [
    postcssPresetEnv({
      autoprefixer: {
        grid: true,
      },
    }),
    postcssPxConvert({
      unitToConvert: 'rem',
      rootValue: 16
    })
  ]
};

这种配置格式与你的示例完全兼容，插件支持标准的 PostCSS 数组格式配置。

📖 文档

• API 文档 - 详细的 API 参考 | English
• 配置说明 - 完整的配置选项说明 | English
• 使用示例 - 丰富的使用示例 | English
• 贡献指南 - 参与项目贡献 | English

🎯 主要功能

1. 单位转换

支持将 px 转换为 rem 或 vw：

/* 输入 */
body {
  font-size: 32px;
  margin: 16px;
  width: 375px;
}

/* 输出 (rem) */
body {
  font-size: 0.85333rem;
  margin: 0.42667rem;
  width: 10.00000rem;
}

/* 输出 (vw) */
body {
  font-size: 8.53333vw;
  margin: 4.26667vw;
  width: 100.00000vw;
}

2. 智能过滤

支持多种过滤方式：

{
  selectorBlackList: ['.ignore', /^\.ant-/],  // 选择器过滤
  propList: ['font-size', 'margin*'],         // 属性过滤
  exclude: [/node_modules/]                   // 文件过滤
}

3. 横屏适配

支持横屏模式下的不同转换规则：

{
  landscape: true,
  landscapeUnit: 'vw',
  landscapeWidth: 568
}

4. 自动生成 flexible.js

{
  injectFlexibleScript: true,
  flexibleScriptPath: './public/flexible.js'
}

🔧 配置选项

更多配置选项请查看 配置说明。

📱 移动端适配

rem 方案

推荐设置 rootValue 为设计稿宽度的 1/10：

// 设计稿宽度 375px
{
  unitToConvert: 'rem',
  rootValue: 37.5
}

// 设计稿宽度 750px
{
  unitToConvert: 'rem',
  rootValue: 75
}

动态设置 rootValue

当项目中有多个设计稿尺寸（如主项目是 750px，而某些第三方组件是基于 375px 设计）时，可以动态设置 rootValue：

{
  unitToConvert: 'rem',
  rootValue: ({ file }) => {
    // 如果是 vant 组件，使用 37.5 作为基准值
    if (file.indexOf('node_modules/vant') !== -1) {
      return 37.5;
    }
    // 其他使用 75 作为基准值
    return 75;
  }
}

vw 方案

直接使用设计稿宽度：

// 设计稿宽度 375px
{
  unitToConvert: 'vw',
  viewportWidth: 375
}

vw + rem 混合方案

通过 unitMap 配置，不同属性可使用不同的转换单位：

{
  unitToConvert: 'rem',      // 默认单位（未配置的单位）
  rootValue: 37.5,
  viewportWidth: 375,
  unitMap: {
    'width': 'vw',           // 布局使用 vw
    'height': 'vw',
    'font-size': 'rem',      // 字体使用 rem
    'margin*': 'rem',        // 间距使用 rem
    'padding*': 'rem',
  }
}

使用建议：

• rem 适合字体和间距，保持相对比例
• vw 适合布局和定位，更好地适应屏幕宽度
• 未在 unitMap 中配置的属性，使用 unitToConvert 指定的默认单位

优先级（从高到低）：

1. 内联注释：/* px-convert:vw */ 或 /* px-convert:rem */
2. unitMap 配置
3. unitToConvert 默认配置

🔌 插件支持

PostCSS 插件