rspack-best-practices

Rspack 最佳实践

编写或审查 Rspack 项目时，请遵循以下规则。

配置

• 使用 rspack.config.ts 和 defineConfig
• 为多页应用显式定义 entry 值
• 保留一个主配置，仅在必要时根据 process.env.NODE_ENV 进行分支
• 让规则条件保持精确且明确（test、include、exclude、resourceQuery）
• 存在等效功能时，优先使用 Rspack 内置插件/加载器，而非社区 JavaScript 替代方案

CLI

如果已安装 @rspack/cli：

• 使用 rspack dev 进行本地开发
• 使用 rspack build 进行生产构建
• 仅使用 rspack preview 进行本地生产预览

类型检查

• 使用 ts-checker-rspack-plugin 集成开发/构建类型检查
• 或将 tsc --noEmit/vue-tsc --noEmit 作为明确的脚本步骤运行

CSS

选择一种策略：

• 现代项目使用内置 CSS（type: 'css' | 'css/auto' | 'css/module'）
• 为兼容 webpack 迁移，使用 css-loader + CssExtractRspackPlugin
• 在纯样式 JavaScript 运行时注入场景中使用 style-loader

可选：

• 当目标是语法降级和添加供应商前缀时，使用 builtin:lightningcss-loader
• 使用 sass-loader/less-loader 预处理 Sass/Less 文件
• 使用 @tailwindcss/webpack 集成 Tailwind CSS

优化打包体积

• 对非关键代码路径优先使用动态 import()
• 尽可能优先选择轻量级库
• 让 target 与实际兼容性要求保持一致

资源管理

• 从项目源代码目录导入由源代码管理的资源，而非从 public 导入
• 通过绝对 URL 路径引用 public 文件
• 优先使用资源模块（asset、asset/resource、asset/inline、asset/source），而非旧版 file-loader/url-loader/raw-loader

性能分析

• 怀疑 JavaScript 侧开销过高时，使用 Node CPU 性能分析（--cpu-prof）
• 使用 RSPACK_PROFILE=OVERVIEW 并分析跟踪输出，查找编译器阶段的瓶颈
• 在可行时，优先将已知的慢速工具链（babel-loader、PostCSS、terser）替换为 Rspack 内置功能

安全

• 启用生产环境 source map 时，不要将 .map 文件发布到公共服务器/CDN

文档

• 最新（v2）文档请参阅 http://rspack.rs/llms.txt
• Rspack v1 文档请参阅 http://v1.rspack.rs/llms.txt