PostCSS 安装与配置 #

安装 PostCSS #

方式一：npm 安装（推荐） #

bash

# 项目本地安装
npm install postcss --save-dev

# 安装常用插件
npm install autoprefixer postcss-cli --save-dev

# 验证安装
npx postcss --version

方式二：全局安装 #

bash

# 全局安装 CLI
npm install postcss-cli autoprefixer --global

# 验证安装
postcss --version

方式三：使用 Yarn #

bash

# 项目本地安装
yarn add postcss autoprefixer postcss-cli --dev

# 全局安装
yarn global add postcss-cli autoprefixer

方式四：使用 pnpm #

bash

# 项目本地安装
pnpm add postcss autoprefixer postcss-cli --save-dev

# 全局安装
pnpm add -g postcss-cli autoprefixer

配置文件 #

PostCSS 支持多种配置文件格式，按优先级从高到低：

1. postcss.config.js（推荐） #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer')({
      overrideBrowserslist: ['> 1%', 'last 2 versions']
    }),
    require('cssnano')({
      preset: 'default'
    })
  ]
}

2. postcss.config.cjs（ES Module 项目） #

javascript

// postcss.config.cjs
module.exports = {
  plugins: [
    require('autoprefixer'),
    require('cssnano')
  ]
}

3. postcss.config.mjs #

javascript

// postcss.config.mjs
import autoprefixer from 'autoprefixer'
import cssnano from 'cssnano'

export default {
  plugins: [
    autoprefixer,
    cssnano
  ]
}

4. .postcssrc.js #

javascript

// .postcssrc.js
module.exports = {
  plugins: {
    autoprefixer: {
      overrideBrowserslist: ['> 1%', 'last 2 versions']
    },
    cssnano: {}
  }
}

5. .postcssrc.json #

json

{
  "plugins": {
    "autoprefixer": {
      "overrideBrowserslist": ["> 1%", "last 2 versions"]
    },
    "cssnano": {}
  }
}

6. .postcssrc.yml #

yaml

plugins:
  autoprefixer:
    overrideBrowserslist:
      - "> 1%"
      - "last 2 versions"
  cssnano: {}

7. package.json #

json

{
  "postcss": {
    "plugins": {
      "autoprefixer": {},
      "cssnano": {}
    }
  }
}

配置文件查找顺序 #

PostCSS 按以下顺序查找配置文件：

text

1. postcss.config.js
2. postcss.config.cjs
3. postcss.config.mjs
4. postcss.config.ts
5. .postcssrc
6. .postcssrc.js
7. .postcssrc.cjs
8. .postcssrc.mjs
9. .postcssrc.ts
10. .postcssrc.json
11. .postcssrc.yml
12. .postcssrc.yaml
13. package.json (postcss 字段)

高级配置 #

环境区分 #

javascript

// postcss.config.js
const isProduction = process.env.NODE_ENV === 'production'

module.exports = {
  plugins: [
    require('autoprefixer'),
    // 只在生产环境压缩
    isProduction && require('cssnano')({
      preset: 'default'
    })
  ].filter(Boolean)
}

函数式配置 #

javascript

// postcss.config.js
module.exports = (ctx) => {
  return {
    plugins: [
      require('autoprefixer')({
        // 根据环境变量配置
        overrideBrowserslist: ctx.env === 'production'
          ? ['> 1%', 'last 2 versions']
          : ['last 1 chrome version']
      }),
      require('postcss-preset-env')({
        stage: ctx.env === 'production' ? 2 : 0
      })
    ]
  }
}

多配置支持 #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer')
  ],
  // 针对不同文件类型
  map: {
    inline: false,
    annotation: true
  }
}

文件匹配配置 #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer')
  ],
  // 排除特定文件
  exclude: 'node_modules/**'
}

与构建工具集成 #

Webpack 集成 #

安装 #

bash

npm install postcss-loader --save-dev

配置 #

javascript

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

内联配置 #

javascript

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('autoprefixer'),
                  require('cssnano')
                ]
              }
            }
          }
        ]
      }
    ]
  }
}

Vite 集成 #

Vite 内置 PostCSS 支持，只需创建配置文件：

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer'),
    require('cssnano')({
      preset: 'default'
    })
  ]
}

Vite 配置 #

javascript

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    postcss: {
      plugins: [
        require('autoprefixer')
      ]
    }
  }
})

Gulp 集成 #

安装 #

bash

npm install gulp-postcss --save-dev

配置 #

javascript

// gulpfile.js
const gulp = require('gulp')
const postcss = require('gulp-postcss')
const autoprefixer = require('autoprefixer')
const cssnano = require('cssnano')

gulp.task('css', () => {
  const plugins = [
    autoprefixer(),
    cssnano()
  ]
  
  return gulp.src('src/*.css')
    .pipe(postcss(plugins))
    .pipe(gulp.dest('dist'))
})

gulp.task('watch', () => {
  gulp.watch('src/*.css', gulp.series('css'))
})

Rollup 集成 #

安装 #

bash

npm install rollup-plugin-postcss --save-dev

配置 #

javascript

// rollup.config.js
import postcss from 'rollup-plugin-postcss'

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife'
  },
  plugins: [
    postcss({
      plugins: [
        require('autoprefixer'),
        require('cssnano')
      ]
    })
  ]
}

Parcel 集成 #

Parcel 自动支持 PostCSS，只需创建配置文件：

javascript

// .postcssrc
{
  "plugins": {
    "autoprefixer": {}
  }
}

Next.js 集成 #

Next.js 内置 PostCSS 支持：

javascript

// postcss.config.js
module.exports = {
  plugins: {
    autoprefixer: {},
    cssnano: {} // 仅在生产环境
  }
}

Nuxt.js 集成 #

javascript

// nuxt.config.js
export default {
  build: {
    postcss: {
      plugins: {
        autoprefixer: {}
      }
    }
  }
}

常用插件安装 #

基础插件 #

bash

# 自动添加浏览器前缀
npm install autoprefixer --save-dev

# CSS 压缩
npm install cssnano --save-dev

# 使用未来 CSS 特性
npm install postcss-preset-env --save-dev

开发增强插件 #

bash

# 嵌套语法
npm install postcss-nested --save-dev

# 变量支持
npm install postcss-simple-vars --save-dev

# Mixin 支持
npm install postcss-mixins --save-dev

# 导入支持
npm install postcss-import --save-dev

功能增强插件 #

bash

# px 转 rem
npm install postcss-pxtorem --save-dev

# CSS 雪碧图
npm install postcss-sprites --save-dev

# RTL 支持
npm install rtlcss --save-dev

配置示例 #

最小配置 #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer')
  ]
}

开发环境配置 #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-nested'),
    require('postcss-simple-vars'),
    require('autoprefixer')
  ]
}

生产环境配置 #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-nested'),
    require('postcss-simple-vars'),
    require('autoprefixer'),
    require('cssnano')({
      preset: ['default', {
        discardComments: {
          removeAll: true
        }
      }]
    })
  ]
}

完整配置示例 #

javascript

// postcss.config.js
const isDev = process.env.NODE_ENV !== 'production'

module.exports = {
  plugins: [
    // 导入处理
    require('postcss-import')({
      path: ['src/styles']
    }),
    
    // 变量
    require('postcss-simple-vars')({
      variables: {
        primary: '#007bff',
        secondary: '#6c757d'
      }
    }),
    
    // 嵌套
    require('postcss-nested'),
    
    // Mixin
    require('postcss-mixins'),
    
    // 自动前缀
    require('autoprefixer')({
      overrideBrowserslist: [
        '> 1%',
        'last 2 versions',
        'not dead'
      ]
    }),
    
    // 未来特性
    require('postcss-preset-env')({
      stage: 2,
      features: {
        'nesting-rules': true
      }
    }),
    
    // 生产环境压缩
    !isDev && require('cssnano')({
      preset: 'default'
    })
  ].filter(Boolean)
}

Source Map 配置 #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer')
  ],
  // 开启 source map
  map: {
    inline: false,      // 不内联
    annotation: true,   // 生成注释
    sourcesContent: true // 包含源内容
  }
}

浏览器兼容性配置 #

browserslist 配置 #

创建 .browserslistrc 文件：

text

# .browserslistrc
> 1%
last 2 versions
not dead
not ie 11

或在 package.json 中配置：

json

{
  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not dead"
  ]
}

不同环境配置 #

json

{
  "browserslist": {
    "production": [
      "> 1%",
      "last 2 versions"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version"
    ]
  }
}

验证配置 #

CLI 验证 #

bash

# 处理单个文件
npx postcss input.css -o output.css

# 查看详细输出
npx postcss input.css -o output.css --verbose

# 开启 source map
npx postcss input.css -o output.css --map

Node.js 验证 #

javascript

// test.js
const postcss = require('postcss')
const autoprefixer = require('autoprefixer')

const css = `
.button {
  display: flex;
  user-select: none;
}
`

postcss([autoprefixer])
  .process(css, { from: undefined })
  .then(result => {
    console.log(result.css)
  })

常见问题 #

配置文件不生效 #

bash

# 检查配置文件位置
ls -la postcss.config.js

# 检查语法
node -e "console.log(require('./postcss.config.js'))"

# 清除缓存
rm -rf node_modules/.cache

插件顺序问题 #

javascript

// 错误：cssnano 在前
module.exports = {
  plugins: [
    require('cssnano'),      // ❌ 应该在最后
    require('autoprefixer')
  ]
}

// 正确：cssnano 在后
module.exports = {
  plugins: [
    require('autoprefixer'),
    require('cssnano')       // ✅ 压缩应该在最后
  ]
}

与 CSS 预处理器冲突 #

javascript

// postcss.config.js
module.exports = {
  plugins: [
    // 只使用兼容性插件，避免与 Less/Sass 功能重复
    require('autoprefixer'),
    require('postcss-preset-env')({
      stage: 2
    })
  ]
}

下一步 #

现在你已经完成了 PostCSS 的安装与配置，接下来学习基本使用开始实际编写！