Back to Details

rsbuild-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rsbuild Best Practices

Rsbuild最佳实践

Apply these rules when writing or reviewing Rsbuild projects.

在编写或评审Rsbuild项目时请遵循以下规则：

Configuration

配置

Use
```
rsbuild.config.ts
```
and
```
defineConfig
```
Use
```
tools.rspack
```
or
```
tools.bundlerChain
```
only when no first-class Rsbuild option exists
Define explicit
```
source.entry
```
values for multi-page applications
In TypeScript projects, prefer
```
tsconfig.json
```
path aliases first

使用
```
rsbuild.config.ts
```
和
```
defineConfig
```
仅当没有原生Rsbuild配置选项可用时，才使用
```
tools.rspack
```
或
```
tools.bundlerChain
```
多页应用请显式定义
```
source.entry
```
值
TypeScript项目优先使用
```
tsconfig.json
```
中的路径别名

CLI

CLI

Use
```
rsbuild dev
```
for local development
Use
```
rsbuild build
```
for production build
Use
```
rsbuild preview
```
only for local production preview
Use
```
rsbuild inspect
```
to inspect final Rsbuild/Rspack configs

本地开发使用
```
rsbuild dev
```
生产环境构建使用
```
rsbuild build
```
仅在本地预览生产构建结果时使用
```
rsbuild preview
```
使用
```
rsbuild inspect
```
查看最终的Rsbuild/Rspack配置

Type checking

类型检查

Use
```
@rsbuild/plugin-type-check
```
for integrated dev/build type checks
Or run
```
tsc --noEmit
```
/
```
vue-tsc --noEmit
```
as an explicit script step

使用
```
@rsbuild/plugin-type-check
```
实现开发/构建流程集成的类型检查
或者将
```
tsc --noEmit
```
/
```
vue-tsc --noEmit
```
作为独立的脚本步骤运行

Bundle size optimization

打包体积优化

Prefer dynamic
```
import()
```
for non-critical code paths
Prefer lightweight libraries where possible
Keep browserslist aligned with real compatibility requirements

非核心代码路径优先使用动态
```
import()
```
尽可能选择轻量级第三方库
保持browserslist配置与实际兼容性要求一致

Asset management

资源管理

Import source-managed assets from project source directories, not from
```
public
```
Reference
```
public
```
files by absolute URL path

项目源码目录中自行管理的资源请通过import引入，不要放在
```
public
```
目录
引用
```
public
```
目录下的文件请使用绝对URL路径

Security

安全

Do not publish
```
.map
```
files to public servers/CDNs when production source maps are enabled

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

Debugging

调试

Run with
```
DEBUG=rsbuild
```
when diagnosing config resolution or plugin behavior
Read generated files in
```
dist/.rsbuild
```
to confirm final config, not assumed config

排查配置解析或插件行为问题时，添加
```
DEBUG=rsbuild
```
参数运行
查看
```
dist/.rsbuild
```
目录下生成的文件确认最终配置，不要依赖假设的配置

Profiling

性能分析

Use Node CPU profiling (
```
--cpu-prof
```
) when JavaScript-side overhead is suspected
Use
```
RSPACK_PROFILE=OVERVIEW
```
and analyze trace output for compiler-phase bottlenecks

怀疑JavaScript侧存在性能开销时，使用Node CPU profiling（
```
--cpu-prof
```
）分析
使用
```
RSPACK_PROFILE=OVERVIEW
```
并分析追踪输出来定位编译阶段的瓶颈

Documentation

文档

For the latest (v2) docs, read http://rsbuild.rs/llms.txt
For Rsbuild v1 docs, read http://v1.rsbuild.rs/llms.txt

最新版本（v2）文档请查看http://rsbuild.rs/llms.txt
Rsbuild v1版本文档请查看http://v1.rsbuild.rs/llms.txt