oops-rspack

基于 Rspack 的前端工程化工具，封装 dev / dev-pre / build / inspect / create 命令，让业务项目零配置上手 Rspack。

特性

• 基于 @rspack/core（Rust bundler），构建速度快
• dev / build 底层引擎统一，避免双引擎差异
• 内置 React Fast Refresh（保存即热更新，保留组件状态）
• 内置分包策略（react-vendor / ui-vendor / utils-vendor / vendors）
• 支持 dev --mode proxy 代理 pre 环境（HTTPS + SwitchHosts + 远程接口转发）
• 自带 create 命令，一行生成 React + TS 项目骨架
• 默认配置可被业务项目 oops.config.js 局部覆盖

安装

全局安装（推荐，用于脚手架创建项目）

npm install -g oops-rspack

项目内安装

npm install -D oops-rspack

快速开始

创建新项目

oops-rspack create my-app
cd my-app
npm install
npm run dev

生成的项目结构：

my-app/
├── index.html
├── oops.config.js
├── package.json
└── src/
    ├── App.jsx
    ├── main.jsx
    └── style.css

在已有项目使用

在项目根目录创建 oops.config.js：

export default {
  entry: './src/main.jsx',
  html: './index.html',
  alias: { '@': './src' },
}

然后执行：

npx oops-rspack dev

命令

| 命令 | 说明 | |---|---| | oops-rspack create <dir> | 创建 React 项目骨架 | | oops-rspack dev | 启动开发服务器（默认 8080 HTTP） | | oops-rspack dev --mode proxy | 启动开发服务器，代理 pre 环境（443 HTTPS） | | oops-rspack build | 生产构建 | | oops-rspack inspect | 打印最终合并后的 Rspack 配置 | | oops-rspack inspect --mode proxy | 打印 proxy profile 下的配置 |

所有命令都支持 --cwd <dir> 指定业务项目目录（默认取 process.cwd()）。

配置文件

工具会在业务项目根目录依次查找：

oops.config.js
oops.config.mjs

找到任意一个就加载其 export default 导出的对象。

字段

| 字段 | 类型 | 默认值 | 说明 | |---|---|---|---| | entry | string | './src/main.jsx' | 入口文件 | | html | string | './index.html' | HTML 模板 | | outDir | string | 'dist' | 输出目录 | | alias | Record<string, string> | {} | 模块别名 | | target | string \| string[] | browserslist:... | 编译目标 | | devServer | object | 见下表 | 覆盖 devServer 默认值 | | rspack | object | {} | 直接覆盖底层 Rspack 配置（resolve / module.rules / optimization / plugins 会做浅合并） |

devServer profile

dev 和 inspect 支持 --mode 参数切换 profile：

| profile | port | host | server | allowedHosts | |---|---|---|---|---| | default | 8080 | 0.0.0.0 | http | all | | proxy | 443 | 0.0.0.0 | https | all |

业务项目 oops.config.js 里的 devServer 字段会覆盖 profile 默认值（浅合并）。例如：

export default {
  devServer: {
    port: 8443,  // 覆盖 proxy profile 的 443，避免低端口权限问题
  },
}

代理 pre 环境（dev --mode proxy）

dev --mode proxy 用于本地代理远程 pre 环境：本地用 HTTPS + 443 起 dev server，浏览器通过 SwitchHosts 用 pre 域名访问，/api 请求转发到远程 pre 服务器。

配置步骤

1. 在 oops.config.js 里配置 proxy：

export default {
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'https://203.119.204.83/',
        changeOrigin: true,
        secure: false,
        headers: {
          Host: 'pre-eads-oops.alibaba-inc.com',
        },
      },
    ],
  },
}

2. 用 SwitchHosts 把代理域名指向 127.0.0.1：

127.0.0.1  pre-eads-oops.alibaba-inc.com

3. 启动：

oops-rspack dev --mode proxy

4. 浏览器访问 https://pre-eads-oops.alibaba-inc.com/（自签名证书会有"不安全"警告，点"高级 → 继续访问"即可）。

注意：443 端口权限

proxy profile 默认用 443 端口，macOS / Linux 普通用户无权监听低端口（≤1023），启动会报：

Error: listen EACCES: permission denied 127.0.0.1:443

解决方式（任选其一）：

• 在 oops.config.js 覆盖端口：devServer: { port: 8443 }（浏览器访问需带 :8443）
• 用 pfctl 把 443 转发到 8443（URL 不带端口，最干净）
• sudo oops-rspack dev --mode proxy（不推荐，node 进程以 root 跑有安全风险）

默认分包

内置 optimization.splitChunks.cacheGroups：

| chunk 名 | 匹配 | priority | |---|---|---| | react-vendor | react, react-dom, scheduler | 40 | | ui-vendor | @arco-design, antd, @alifd | 30 | | utils-vendor | lodash, lodash-es, dayjs, axios | 20 | | vendors | 其他 node_modules | 10 |

priority 高的先匹配，避免依赖被错误归到 vendors 里。

自签名证书依赖

dev --mode proxy 启动 HTTPS 时，dev-server 需要生成自签名 SSL 证书，依赖 selfsigned 包。本工具已将其声明为 dependencies，安装时会自动装好，无需手动安装。

License

MIT