Rsbuild 1.0 迁移指南：从 0.x 版本升级的关键变化-优快云博客

Rsbuild 1.0 迁移指南：从 0.x 版本升级的关键变化

rsbuild Unleash the power of Rspack with the out-of-the-box build tool. 项目地址: https://gitcode.com/gh_mirrors/rs/rsbuild

前言

Rsbuild 1.0 版本带来了多项重要改进和架构调整，这些变化旨在提升构建性能、优化开发体验并增强配置灵活性。本文将详细介绍从 Rsbuild 0.x 迁移到 1.0 版本需要注意的关键变更点，帮助开发者顺利完成升级。

核心变更概览

Rsbuild 1.0 的主要改进集中在以下几个方面：

CSS 处理优化：默认使用 Lightning CSS 替代传统方案
多环境配置重构：引入更灵活的 environments 配置方式
构建目标简化：移除了 targets 配置
配置校验增强：默认启用 Rspack 配置校验
API 和配置项调整：多项配置项被重命名或移除

重要变更详解

1. Lightning CSS 成为默认 CSS 处理器

Rsbuild 1.0 默认启用了 lightningcss-loader 来处理 CSS 文件，这一变化带来了显著的性能提升：

性能优势：Lightning CSS 是基于 Rust 的高性能 CSS 处理器，编译速度比传统方案快 2-5 倍
功能变化：取代了 autoprefixer 来添加浏览器前缀
兼容性处理：如果项目仍需使用 autoprefixer，可通过 postcss 配置文件启用

// postcss.config.cjs
module.exports = {
  plugins: {
    autoprefixer: {},
  },
};

2. 多环境配置重构

1.0 版本彻底重构了多环境配置方式，用 environments 替代了原有的 targets 配置：

旧版配置方式：

export default {
  output: {
    targets: ['web', 'node'],
  },
};

新版配置方式：

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};

这种新方式不仅支持多目标构建，还能针对不同环境配置更多差异化参数，如不同的入口文件、别名、浏览器兼容性要求等。

3. 默认禁用 Polyfill

出于优化包体积的考虑，1.0 版本默认将 output.polyfill 设置为 'off'。如果项目需要 polyfill，需要显式配置：

export default {
  output: {
    polyfill: 'usage', // 或 'entry'
  },
};

4. 装饰器语法版本升级

Rsbuild 1.0 默认使用 2022-11 装饰器版本，与 TypeScript 5.0+ 和 esbuild 0.21.0+ 保持一致。如需使用旧版装饰器语法，需要特别配置：

export default {
  source: {
    decorators: {
      version: 'legacy',
    },
  },
};

配置项变更详解

1. 别名配置变更

旧版：

export default {
  source: {
    alias: (alias, { target }) => {
      if (target === 'node') {
        alias['@common'] = './src/node/common';
      }
    },
  },
};

新版：

export default {
  environments: {
    node: {
      source: {
        alias: {
          '@common': './src/node/common',
        },
      },
    },
  },
};

2. 入口文件配置变更

旧版：

export default {
  source: {
    entry({ target }) {
      if (target === 'web') {
        return { index: './src/index.client.js' };
      }
    },
  },
};

新版：

export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
    },
  },
};

3. 浏览器兼容性配置变更

旧版：

export default {
  output: {
    overrideBrowserslist: {
      web: ['iOS >= 9'],
    },
  },
};

新版：

export default {
  environments: {
    web: {
      output: {
        overrideBrowserslist: ['iOS >= 9'],
      },
    },
  },
};

其他重要变更

1. HTML 压缩调整

Rsbuild 1.0 移除了内置的 HTML 压缩功能，原因是：

原有压缩工具性能不足
HTML 压缩带来的收益相对有限
可通过独立插件实现相同功能

如需 HTML 压缩，可安装专用插件：

import { pluginHtmlMinifierTerser } from 'rsbuild-plugin-html-minifier-terser';

export default {
  plugins: [pluginHtmlMinifierTerser()],
};

2. 开发服务器配置变更

部分开发服务器相关配置项被重命名或调整：

export default {
  // 旧版
  dev: {
    startUrl: true,
    client: {
      port: '<port>',
    },
  },
  
  // 新版
  server: {
    open: true,
  },
  dev: {
    client: {
      port: '', // 默认使用 location.port
    },
  },
};

3. 应用图标配置增强

应用图标配置现在支持更丰富的 manifest 定义：

export default {
  html: {
    appIcon: {
      icons: [
        { src: './src/icon.png', size: 180 },
        { src: './src/icon-512.png', size: 512 },
      ],
    },
  },
};