2022-07-01 16:47:25 +08:00
|
|
|
|
---
|
|
|
|
|
|
title: 构建配置
|
2022-10-18 13:54:20 +08:00
|
|
|
|
order: 14
|
2022-07-01 16:47:25 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
2022-10-19 15:20:02 +08:00
|
|
|
|
ice.js 支持常用的构建配置项，所有的配置项在 `ice.config.mts` 中设置。
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
## 配置文件
|
|
|
|
|
|
|
|
|
|
|
|
### 构建配置文件
|
|
|
|
|
|
|
2022-10-19 15:20:02 +08:00
|
|
|
|
为了获取良好的类型提示，ice.js 推荐以 `ice.config.mts` 作为配置文件：
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
publicPath: '/',
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 兼容性配置
|
|
|
|
|
|
|
|
|
|
|
|
构建的兼容性配置推荐配置在 `.browserslistrc` 文件中：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
chrome 55
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
更多配置请参考 [browserslist 文档](https://github.com/browserslist/browserslist#readme)
|
|
|
|
|
|
|
|
|
|
|
|
## 配置项
|
|
|
|
|
|
|
|
|
|
|
|
### alias
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`Record<string, string | false>`
|
2022-10-12 17:07:23 +08:00
|
|
|
|
- 默认值：`{ "@": "./src/" }`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
2022-10-13 17:37:38 +08:00
|
|
|
|
在 ice.js 默认内置常用的 alias 规则，因此项目大多数时候不需要配置即可更加简单的导入模块了：
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
```diff
|
|
|
|
|
|
-import CustomTips from '../../../components/CustomTips';
|
|
|
|
|
|
+import CustomTips from '@/components/CustomTips';
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
如果需要配置别名对 import 路径进行映射：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
alias: {
|
|
|
|
|
|
pages: './src/pages',
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2022-11-04 14:39:41 +08:00
|
|
|
|
### crossOriginLoading
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`false | 'anonymous' | 'use-credentials'`
|
|
|
|
|
|
- 默认值：`false`
|
|
|
|
|
|
|
|
|
|
|
|
配置
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-11-04 14:39:41 +08:00
|
|
|
|
crossOriginLoading: 'anonymous'
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-11-04 14:39:41 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
指定 webpack 启用 [cross-origin](https://webpack.js.org/configuration/output/#outputcrossoriginloading) 去加载 chunk。
|
|
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
### define
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`Record<string, string | boolean>`
|
2023-05-08 12:04:07 +08:00
|
|
|
|
- 默认值：`{ 'process.env.NODE_ENV': 'development' | 'production'; 'import.meta.renderer': 'client' | 'server'; 'import.meta.target': string; }`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
2023-05-08 12:04:07 +08:00
|
|
|
|
在编译时将代码中的全局变量替换成其他值或者表达式。一般用于区分不同环境以执行不同代码逻辑。
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
define: {
|
2023-05-08 12:04:07 +08:00
|
|
|
|
ASSETS_VERSION: JSON.stringify('0.1.0'),
|
|
|
|
|
|
AGE: '11',
|
2022-07-01 16:47:25 +08:00
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
在代码中直接使用对应定义的变量：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
console.log(ASSETS_VERSION);
|
2023-05-08 12:04:07 +08:00
|
|
|
|
// 最终会被编译成：
|
|
|
|
|
|
// console.log('0.1.0');
|
|
|
|
|
|
|
|
|
|
|
|
console.log(AGE);
|
|
|
|
|
|
// 最终会被编译成：
|
|
|
|
|
|
// console.log(11);
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2023-05-08 12:04:07 +08:00
|
|
|
|
注意，在编译时，将会对你设置的 `define` 替换值进行类似字符串拼接的方式生成新的代码。因此：
|
|
|
|
|
|
- 对于引用数据类型（`function` 和 `object`），需要使用 `JSON.stringify()` 方法处理
|
|
|
|
|
|
- 对于要替换的全局变量是字符串时，需要使用 `JSON.stringify()` 方法处理或者多添加一对引号（如 `"'hello world'"`），否则就是一个标识符，有可能跟预期结果不一致的情况
|
|
|
|
|
|
|
2022-10-19 15:20:02 +08:00
|
|
|
|
对于运行时变量，ice.js 更加推荐通过[环境变量](./env.md)的方式注入。
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
2022-11-15 15:03:30 +08:00
|
|
|
|
### dataLoader
|
2022-09-22 15:56:32 +08:00
|
|
|
|
|
2022-12-26 16:50:28 +08:00
|
|
|
|
- 类型： `boolean | { fetcher: { packageName: string; method: string } }`
|
2022-09-22 15:56:32 +08:00
|
|
|
|
- 默认值 `true`
|
|
|
|
|
|
|
2022-12-26 16:50:28 +08:00
|
|
|
|
是否启用内置的数据预加载能力以及自定义发送者（fetcher）。
|
2022-11-07 13:57:06 +08:00
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
### publicPath
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`string`
|
|
|
|
|
|
- 默认值：`/`
|
|
|
|
|
|
|
|
|
|
|
|
配置 Webpack 的 [output.publicPath](https://webpack.js.org/configuration/output/#output-publicpath) 属性，仅在运行 build 命令时生效。
|
|
|
|
|
|
|
|
|
|
|
|
### devPublicPath
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`string`
|
|
|
|
|
|
- 默认值：`/`
|
|
|
|
|
|
|
|
|
|
|
|
同 publicPath 仅在执行 start 时生效。
|
|
|
|
|
|
|
|
|
|
|
|
### hash
|
|
|
|
|
|
|
2022-11-07 13:57:06 +08:00
|
|
|
|
- 类型：`boolean | string`
|
|
|
|
|
|
- 默认值：`false`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
如果希望构建后的资源带 hash 版本，可以将 hash 设置为 `true`，也可以设置为 `contenthash` 按文件内容生成 hash 值：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
hash: 'contenthash',
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### externals
|
|
|
|
|
|
|
2022-11-07 13:57:06 +08:00
|
|
|
|
- 类型：`Record<string, string>`
|
|
|
|
|
|
- 默认值：`{}`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
设置哪些模块不打包，转而通过 `<script>` 或其他方式引入，比如：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
externals: {
|
|
|
|
|
|
react: 'React',
|
2023-05-10 11:18:20 +08:00
|
|
|
|
'react-dom': 'ReactDOM',
|
2022-07-01 16:47:25 +08:00
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
对应在 `document.ts` 或者页面模版里添加 CDN 文件：
|
|
|
|
|
|
|
|
|
|
|
|
```diff
|
|
|
|
|
|
import { Main, Scripts } from 'ice';
|
|
|
|
|
|
|
|
|
|
|
|
function Document() {
|
|
|
|
|
|
return (
|
|
|
|
|
|
<html lang="en">
|
|
|
|
|
|
<body>
|
|
|
|
|
|
<Main />
|
2023-05-10 11:18:20 +08:00
|
|
|
|
+ <script crossOrigin="" src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
|
|
|
|
|
|
+ <script crossOrigin="" src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
|
2022-07-01 16:47:25 +08:00
|
|
|
|
<Scripts />
|
|
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
|
|
|
|
|
);
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
export default Document;
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### outputDir
|
|
|
|
|
|
|
2022-11-07 13:57:06 +08:00
|
|
|
|
- 类型：`string`
|
|
|
|
|
|
- 默认值：`build`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
构建产物输出目录，默认为 `build` 目录
|
|
|
|
|
|
|
|
|
|
|
|
### proxy
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`object`
|
|
|
|
|
|
- 默认值：`{}`
|
|
|
|
|
|
|
2023-05-19 14:10:01 +08:00
|
|
|
|
配置 dev 开发阶段的代理功能。配置项与 Webpack [devServer.proxy](https://webpack.js.org/configuration/dev-server/#devserverproxy) 保持一致。
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
proxy: {
|
|
|
|
|
|
'/api': {
|
|
|
|
|
|
target: 'http://jsonplaceholder.typicode.com/',
|
|
|
|
|
|
changeOrigin: true,
|
|
|
|
|
|
pathRewrite: { '^/api' : '' },
|
|
|
|
|
|
},
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### minify
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`boolean`
|
|
|
|
|
|
- 默认值：`true`
|
|
|
|
|
|
|
|
|
|
|
|
压缩产物，目前默认仅在 build 阶段生效
|
|
|
|
|
|
|
|
|
|
|
|
### dropLogLevel
|
|
|
|
|
|
|
2023-07-07 18:02:56 +08:00
|
|
|
|
- 类型：`boolean | DropType[] | DropType`
|
|
|
|
|
|
- 默认值：`false`，不移除任何 console 代码
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
2023-07-07 18:02:56 +08:00
|
|
|
|
压缩代码时移除 console.* 相关代码，配置为true时，移除所有console.*相关代码。当想移除部分console代码，例如想要移除console.log和console.error时，可以配置为
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
dropLog: ['error', 'log'],
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
|
|
|
|
|
也可以根据console等级来进行移除
|
|
|
|
|
|
```js
|
|
|
|
|
|
// console 等级为 trace < debug < log < info < warn < error
|
|
|
|
|
|
// 例如想要移除trace、debug、log时可以像下面这样配置
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
dropLog: 'log',
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
### compileDependencies
|
|
|
|
|
|
|
2022-07-07 18:56:14 +08:00
|
|
|
|
- 类型：`array | boolean`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
- 默认值：`[]`
|
|
|
|
|
|
|
|
|
|
|
|
默认情况下为了保证 dev 开发阶段的体验，`node_modules` 下文件不会进行编译，而考虑到 build 阶段对代码体积的极致优化以及兼容性保证，将会对 `node_modules` 下内容也进行编译。
|
2023-05-17 14:01:17 +08:00
|
|
|
|
|
|
|
|
|
|
如果 dev 阶段需要额外编译一些依赖，build 阶段下仍然全量编译，可以参考下面的方式在 dev 阶段通过正则追加一些配置：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
compileDependencies: process.env.NODE_ENV === 'development' ? [/@alifd\/next/, /need-compile/] : true,
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
:::caution
|
|
|
|
|
|
如果 build 阶段仍然需要全量编译，请务必增加环境判断
|
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
|
|
如果希望 dev 和 build 阶段均编译 `node_modules`，可以设置为 `true`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
compileDependencies: true,
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2023-05-17 14:01:17 +08:00
|
|
|
|
如果明确知道哪些依赖需要进行编译也可以通过正则方式进行设置：（对 dev 和 build 同时生效）
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
compileDependencies: [/@alifd\/next/, /need-compile/],
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2022-11-07 13:57:06 +08:00
|
|
|
|
### postcss
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`ProcessOptions & { plugins?: (string | [string, Record<string, any>?])[] };`
|
|
|
|
|
|
- 默认值：`{}`
|
|
|
|
|
|
|
|
|
|
|
|
用于添加 postcss 自定义配置。示例如下：
|
|
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-11-07 13:57:06 +08:00
|
|
|
|
postcss: {
|
|
|
|
|
|
plugins: [
|
|
|
|
|
|
'postcss-px-to-viewport-8-plugin',
|
|
|
|
|
|
{
|
|
|
|
|
|
// ...
|
|
|
|
|
|
},
|
|
|
|
|
|
],
|
|
|
|
|
|
syntax: 'sugarss',
|
|
|
|
|
|
}
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-11-07 13:57:06 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
ice.js 内置的 postcss 配置是：
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"plugins": [
|
|
|
|
|
|
["postcss-nested"],
|
|
|
|
|
|
["postcss-preset-env", {
|
|
|
|
|
|
"stage": 3,
|
|
|
|
|
|
"autoprefixer": {
|
|
|
|
|
|
"flexbox": "no-2009",
|
|
|
|
|
|
},
|
|
|
|
|
|
"features": {
|
|
|
|
|
|
"custom-properties": false,
|
|
|
|
|
|
},
|
|
|
|
|
|
}],
|
|
|
|
|
|
["postcss-plugin-rpx2vw"],
|
|
|
|
|
|
],
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
如果需要完全重写 postcss 配置或修改内置的 postcss 配置，需要在项目根目录下新增 `postcss.config.js` 文件并加入配置，工程上会清空内置的 postcss 配置。
|
|
|
|
|
|
|
|
|
|
|
|
```js title="postcss.config.js"
|
|
|
|
|
|
module.exports = {
|
|
|
|
|
|
plugins: [
|
|
|
|
|
|
[
|
|
|
|
|
|
'postcss-preset-env',
|
|
|
|
|
|
// 修改 postcss-preset-env 的选项
|
|
|
|
|
|
{
|
|
|
|
|
|
stage: 2,
|
|
|
|
|
|
}
|
|
|
|
|
|
]
|
|
|
|
|
|
],
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2022-11-04 17:07:52 +08:00
|
|
|
|
### polyfill
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`'usage' | 'entry' | false`
|
|
|
|
|
|
- 默认值：`false`
|
|
|
|
|
|
|
|
|
|
|
|
框架提供了多种 polyfill 的方式，开发者可以按实际情况选择对应的设置：
|
2022-11-07 13:57:06 +08:00
|
|
|
|
|
2022-11-04 17:07:52 +08:00
|
|
|
|
- `usage` 按开发者使用的语法自动引入对应的 `polyfill`，适用于 `node_modules` 也进行编译的场景（一定程度上影响编译效率以及三方依赖二次编译造成的代码冗余）
|
|
|
|
|
|
- `entry` 自动引入 browser（浏览器）需要兼容的 `polyfill`，适用于 `node_modules` 依赖不进行编译的场景（可能存在大量未被使用的 `polyfill` 被引入）
|
|
|
|
|
|
|
|
|
|
|
|
> 如果面向现代浏览器进行开发，大量 ES 语法均不需要引入 Polyfill，我们推荐不开启 `polyfill` 配置。如果你的代码或者三方依赖要求兼容到 IE 11 等浏览器，可以选择主动引入指定语法的 polyfill 或者开启 `polyfill` 配置。
|
|
|
|
|
|
|
2022-07-08 17:34:11 +08:00
|
|
|
|
### transform
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`(code:string, id: string) => string | {code: string; map?: SourceMap | null;}`
|
|
|
|
|
|
- 默认值：`undefined`
|
|
|
|
|
|
|
|
|
|
|
|
通过 `transform` 配置实现代码的转化：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
import { transformSync } from '@babel/core';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-08 17:34:11 +08:00
|
|
|
|
transform: (originalCode, id) => {
|
|
|
|
|
|
if (!id.includes('node_modules')) {
|
|
|
|
|
|
// 借助 babel 编译
|
|
|
|
|
|
const { code, map } = transformSync(originalCode, {
|
|
|
|
|
|
plugins: ['transform-decorators-legacy'],
|
|
|
|
|
|
});
|
|
|
|
|
|
return { code, map };
|
|
|
|
|
|
}
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-08 17:34:11 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2022-10-19 15:20:02 +08:00
|
|
|
|
> ice.js 内置通过 `swc` 提升编译体验，如果在 `transform` 配置上过多依赖 babel 等工具将可以能造成编译性能瓶颈
|
2022-07-08 17:34:11 +08:00
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
### ssr
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`boolean`
|
|
|
|
|
|
- 默认值：`false`
|
|
|
|
|
|
|
|
|
|
|
|
是否开启 SSR 能力，更多 SSR 相关内容参考 [SSR 文档](./ssr)。
|
|
|
|
|
|
|
|
|
|
|
|
### ssg
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`boolean`
|
|
|
|
|
|
- 默认值：`true`
|
|
|
|
|
|
|
|
|
|
|
|
是否开启 SSG 能力，更多 SSG 相关内容参考 [SSG 文档](./ssg)。
|
|
|
|
|
|
|
|
|
|
|
|
### server
|
|
|
|
|
|
|
2023-03-06 15:03:10 +08:00
|
|
|
|
- 类型：`{ format: 'esm' | 'cjs'; bundle: boolean; ignores: IgnorePattern[]; externals: string[]; onDemand: boolean; }`
|
|
|
|
|
|
- 默认值：`{ format: 'esm', bundle: false, ignores: [], externals: [], onDemand: false }`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
SSR / SSG 产物标准，推荐以 ESM 标准进行执行，如果希望打包成一个 cjs 模块，可以进行如下设置：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
server: {
|
|
|
|
|
|
format: 'cjs',
|
|
|
|
|
|
bundle: true,
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2022-09-16 10:58:10 +08:00
|
|
|
|
可以通过 `ignores` 参数，为 SSR / SSG 产物过滤指定文件：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-09-16 10:58:10 +08:00
|
|
|
|
server: {
|
|
|
|
|
|
ignores: [{
|
|
|
|
|
|
resourceRegExp: /^\.\/locale$/,
|
|
|
|
|
|
contextRegExp: /moment$/,
|
|
|
|
|
|
}]
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-09-16 10:58:10 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
其中：
|
2022-11-07 13:57:06 +08:00
|
|
|
|
|
|
|
|
|
|
- resourceRegExp 对应文件的匹配路径
|
|
|
|
|
|
- contextRegExp （可选）对应文件内容的匹配规则
|
2022-09-16 10:58:10 +08:00
|
|
|
|
|
2022-12-26 17:00:53 +08:00
|
|
|
|
通过 `externals` 参数，可以在构建 Server 端产物时 external 指定内容：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
server: {
|
|
|
|
|
|
externals: ['react', 'react-dom']
|
|
|
|
|
|
},
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2023-03-06 15:03:10 +08:00
|
|
|
|
通过 `onDemand` 参数，可以在执行 Server 端产物时，按需构建所需的问题，并且提供体验良好的模块热更新服务：
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
server: {
|
|
|
|
|
|
onDemand: true,
|
|
|
|
|
|
format: 'esm',
|
|
|
|
|
|
},
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
### routes
|
|
|
|
|
|
|
2022-12-07 19:17:17 +08:00
|
|
|
|
- 类型：`{ ignoreFiles: string[]; defineRoutes: (route: DefineRouteFunction) => void }`
|
2022-07-01 16:47:25 +08:00
|
|
|
|
- 默认值：`{}`
|
|
|
|
|
|
|
2022-12-07 19:17:17 +08:00
|
|
|
|
#### ignoreFiles
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
2022-12-07 19:17:17 +08:00
|
|
|
|
用于忽略 `src/pages` 下的文件被处理成路由模块，使用 glob 表达式([minimatch](https://github.com/isaacs/minimatch))对文件路径匹配。
|
|
|
|
|
|
|
|
|
|
|
|
```ts
|
2022-07-01 16:47:25 +08:00
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
routes: {
|
2022-12-07 19:17:17 +08:00
|
|
|
|
// 忽略 src/pages 下所有 components 目录
|
2022-07-01 16:47:25 +08:00
|
|
|
|
ignoreFiles: ['**/components/**'],
|
2022-12-07 19:17:17 +08:00
|
|
|
|
},
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
#### defineRoutes
|
|
|
|
|
|
|
|
|
|
|
|
对于约定式路由不满足的场景，可以通过以下方式自定义路由地址。
|
|
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
routes: {
|
2022-07-01 16:47:25 +08:00
|
|
|
|
defineRoutes: (route) => {
|
|
|
|
|
|
// 将 /about-me 路由访问内容指定为 about.tsx
|
2022-12-07 19:17:17 +08:00
|
|
|
|
// 第一个参数是路由地址
|
|
|
|
|
|
// 第二个参数是页面组件的相对地址（前面不能带 `/`），相对于 `src/pages` 目录
|
2022-07-01 16:47:25 +08:00
|
|
|
|
route('/about-me', 'about.tsx');
|
|
|
|
|
|
|
2022-12-07 19:17:17 +08:00
|
|
|
|
// 嵌套路由的场景需要使用第三个 callback 参数来定义嵌套路由
|
2022-07-01 16:47:25 +08:00
|
|
|
|
route('/', 'layout.tsx', () => {
|
|
|
|
|
|
route('/product', 'products.tsx');
|
|
|
|
|
|
});
|
|
|
|
|
|
},
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2023-02-23 19:28:32 +08:00
|
|
|
|
:::caution
|
|
|
|
|
|
同一个路由组件只能分配一条路由规则，即同时执行以下语句时，仅生效后执行的逻辑。
|
|
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
|
route('/about-me', 'about.tsx');
|
|
|
|
|
|
route('/about-you', 'about.tsx');
|
|
|
|
|
|
```
|
|
|
|
|
|
:::
|
|
|
|
|
|
|
2023-03-06 15:03:10 +08:00
|
|
|
|
#### config
|
|
|
|
|
|
|
|
|
|
|
|
对于简单的自定义场景，通过 `defineRoutes` 可以快速在约定式路由的基础上进行自定义。但对于大量自定义或者原配置式路由的升级项目，支持以 `config` 的字段指定路由信息：
|
|
|
|
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig({
|
|
|
|
|
|
routes: {
|
|
|
|
|
|
config: [
|
|
|
|
|
|
{
|
|
|
|
|
|
path: 'rewrite',
|
|
|
|
|
|
// 从 src/page 开始计算路径，并且需要写后缀。
|
|
|
|
|
|
component: 'sales/layout.tsx',
|
|
|
|
|
|
children: [
|
|
|
|
|
|
{
|
|
|
|
|
|
path: '/favorites',
|
|
|
|
|
|
component: 'sales/favorites.tsx',
|
|
|
|
|
|
},
|
|
|
|
|
|
{
|
|
|
|
|
|
path: 'overview',
|
|
|
|
|
|
component: 'sales/overview.tsx',
|
|
|
|
|
|
},
|
|
|
|
|
|
{
|
|
|
|
|
|
path: 'recommends',
|
|
|
|
|
|
component: 'sales/recommends.tsx',
|
|
|
|
|
|
},
|
|
|
|
|
|
],
|
|
|
|
|
|
},
|
|
|
|
|
|
{
|
|
|
|
|
|
path: '/',
|
|
|
|
|
|
component: 'index.tsx',
|
|
|
|
|
|
},
|
|
|
|
|
|
],
|
|
|
|
|
|
},
|
|
|
|
|
|
});
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
### sourceMap
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`boolean | string`
|
|
|
|
|
|
- 默认值：`development` 模式：默认为 'cheap-module-source-map'，支持通过 `false` 关闭，不支持设置为其他枚举值。`production` 模式：默认 `false`。
|
|
|
|
|
|
|
2023-02-24 17:22:18 +08:00
|
|
|
|
### splitChunks @deprecated
|
2022-08-29 16:16:49 +08:00
|
|
|
|
|
2022-11-15 15:03:30 +08:00
|
|
|
|
:::caution
|
2024-03-20 16:06:58 +08:00
|
|
|
|
不再建议使用，能力由 codeSplitting 替代
|
2022-11-15 15:03:30 +08:00
|
|
|
|
:::
|
|
|
|
|
|
|
2023-02-24 17:22:18 +08:00
|
|
|
|
默认会根据模块体积自动拆分 chunks，有可能会出现多个 bundle。如果不希望打包产物出现过多 bundle ，可设置成 `false`。
|
|
|
|
|
|
|
|
|
|
|
|
### codeSplitting
|
|
|
|
|
|
|
2023-07-17 10:44:15 +08:00
|
|
|
|
- 类型：`boolean | 'vendors' | 'page' | 'chunks' | 'page-vendors'`
|
2022-08-29 16:16:49 +08:00
|
|
|
|
- 默认值：`true`
|
|
|
|
|
|
|
2023-02-24 17:22:18 +08:00
|
|
|
|
框架内置了三种分包策略分别为 `chunks`（默认策略，无需额外设置），`page` 和 `vendors`。
|
|
|
|
|
|
|
|
|
|
|
|
- `vendors` 策略：将异步 chunks 里的三方依赖统一打入到 vendor.js 中，避免重复，在依赖不变的情况下有效利用缓存。缺陷是如果项目过大会导致单文件尺寸过大。
|
|
|
|
|
|
- `page` 策略：所有路由级别组件按需加载，如果需保留原 `splitChunks: false` 的效果，配置该策略 。
|
2023-07-17 10:44:15 +08:00
|
|
|
|
- `page-vendors` 策略：在 `page` 策略的基础上，将异步 chunks 里的三方依赖统一打入到 vendor.js 中，以达到有效利用缓存的结果。
|
2023-02-24 17:22:18 +08:00
|
|
|
|
- `chunks` 策略：在路由级别组件按需加载的基础上，根据模块体积大小自动拆分 chunks，为框架默认推荐策略。
|
|
|
|
|
|
|
|
|
|
|
|
如果存在特殊场景期望关闭分包能力，可以设置成 `false`。
|
2022-08-29 16:16:49 +08:00
|
|
|
|
|
2022-07-21 15:05:10 +08:00
|
|
|
|
### syntaxFeatures
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`{ exportDefaultFrom: boolean; functionBind: boolean; }`
|
|
|
|
|
|
- 默认值：`undefined`
|
|
|
|
|
|
|
2022-10-19 15:20:02 +08:00
|
|
|
|
ice.js 内置了大量 ES 语法支持，便于开发者进行编码。对于 [proposal-export-default-from](https://github.com/tc39/proposal-export-default-from) 和 [proposal-bind-operator](https://github.com/tc39/proposal-bind-operator) 由于其提案进度较慢，我们并不推荐使用。如果希望支持该语法，可以主动配置 `syntaxFeatures` 进行启用。
|
2022-07-21 15:05:10 +08:00
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
### tsChecker
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`boolean`
|
|
|
|
|
|
- 默认值：`false`
|
|
|
|
|
|
|
|
|
|
|
|
默认关闭 TypeScript 类型检测，如需开启配置为 `true` 即可。
|
|
|
|
|
|
|
|
|
|
|
|
### eslint
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`boolean | object`
|
|
|
|
|
|
- 默认值：`undefined`
|
|
|
|
|
|
|
|
|
|
|
|
配置说明：
|
2022-07-07 18:56:14 +08:00
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
- `false`：不检测 eslint 错误
|
|
|
|
|
|
- `true`：将 eslint 错误展示在预览页面上
|
|
|
|
|
|
- `object`: 仅 Webpack 模式支持，表现等同于 true，支持配置 [eslint-webpack-plugin](https://github.com/webpack-contrib/eslint-webpack-plugin) 的更多参数
|
|
|
|
|
|
|
|
|
|
|
|
### mock
|
|
|
|
|
|
|
2022-07-07 18:56:14 +08:00
|
|
|
|
- 类型：`{ exclude: string[] }`
|
|
|
|
|
|
- 默认值：`{}`
|
|
|
|
|
|
|
|
|
|
|
|
配置忽略 mock 的文件。
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-07 18:56:14 +08:00
|
|
|
|
mock: {
|
|
|
|
|
|
// 忽略 mock 目录中 custom 目录下的文件以及 api.ts 文件
|
|
|
|
|
|
exclude: ["custom/**", "api.ts"]
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-07 18:56:14 +08:00
|
|
|
|
```
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
2023-07-06 10:41:44 +08:00
|
|
|
|
### htmlGenerating
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`boolean`
|
|
|
|
|
|
- 默认值：`true`
|
|
|
|
|
|
|
|
|
|
|
|
如果产物不想生成 html，可以设置为 `false`，在 SSG 开启的情况下，强制关闭 html 生成，将导致 SSG 失效。
|
|
|
|
|
|
|
2022-10-12 17:07:23 +08:00
|
|
|
|
### plugins
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`PluginList<Config, OverwritePluginAPI>`
|
|
|
|
|
|
- 默认值：`[]`
|
|
|
|
|
|
|
|
|
|
|
|
添加插件
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
import customPlugin from './custom-plugin';
|
|
|
|
|
|
import myPlugin from '@ice/my-plugin';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-10-12 17:07:23 +08:00
|
|
|
|
plugins: [
|
|
|
|
|
|
customPlugin(),
|
|
|
|
|
|
myPlugin(),
|
|
|
|
|
|
],
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-10-12 17:07:23 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
### webpack
|
|
|
|
|
|
|
2022-11-07 13:57:06 +08:00
|
|
|
|
:::tip
|
|
|
|
|
|
ice.js 对 webpack 构建配置进行了定制，并借助 esbuild 等工具提升用户开发体验，直接修改 webpack 配置的方式并不推荐。
|
|
|
|
|
|
:::
|
|
|
|
|
|
|
2022-07-01 16:47:25 +08:00
|
|
|
|
- 类型：`(config: WebpackConfig, taskConfig: TaskConfig) => WebpackConfig`
|
|
|
|
|
|
- 默认值：`true`
|
|
|
|
|
|
|
2022-10-19 15:20:02 +08:00
|
|
|
|
ice.js 默认基于 webpack 5 进行构建，在上述提供的构建配置无法满足的情况下，用户可以定制 webpack 配置：
|
2022-07-01 16:47:25 +08:00
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
import SpeedMeasurePlugin from 'speed-measure-webpack-plugin';
|
|
|
|
|
|
|
2022-11-11 11:02:51 +08:00
|
|
|
|
export default defineConfig(() => ({
|
2022-07-01 16:47:25 +08:00
|
|
|
|
webpack: (webpackConfig) => {
|
|
|
|
|
|
if (process.env.NODE_ENV !== 'test') {
|
|
|
|
|
|
// 添加 webpack 插件
|
|
|
|
|
|
webpackConfig.plugins?.push(new SpeedMeasurePlugin());
|
|
|
|
|
|
}
|
|
|
|
|
|
return webpackConfig;
|
|
|
|
|
|
},
|
2022-11-11 11:02:51 +08:00
|
|
|
|
}));
|
2022-07-01 16:47:25 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2023-09-20 15:17:28 +08:00
|
|
|
|
### cssModules
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`{ localIdentName: string }`
|
|
|
|
|
|
- 默认值：`{}`
|
|
|
|
|
|
|
|
|
|
|
|
构建 cssModules 时，定制 class 名称的生成规则，配置参考 https://webpack.js.org/loaders/css-loader/#localidentname
|
|
|
|
|
|
|
|
|
|
|
|
例如，配置 '[hash:8]' 可以只保留 hash 值，以精简 HTML 大小及 CSS 文件大小。默认情况 `className="custom-head-tab-wrap"` 会被构建为 `class="custom-head-tab-wrap--rAEgGaqM"`，自定义构建规则后后样式名会被精简为 `class="rAEgGaqM"`。
|
|
|
|
|
|
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
cssModules: {
|
|
|
|
|
|
localIdentName: '[hash:8]'
|
|
|
|
|
|
},
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2024-03-20 16:06:58 +08:00
|
|
|
|
### optimization
|
|
|
|
|
|
|
|
|
|
|
|
- 类型：`{ disableRouter: boolean; optimizePackageImport: boolean | string[] }`
|
|
|
|
|
|
- 默认值：`{}`
|
|
|
|
|
|
|
|
|
|
|
|
框架提供内置的优化能力，针对不同场景提供优化策略：
|
|
|
|
|
|
- `disableRouter`：默认为 `false`，如果希望关闭路由能力，可以设置为 `true`。主要应用不存在依赖路由能力的场景，比如不存在 SPA 页面跳转。
|
|
|
|
|
|
- `optimizePackageImport`：默认为 `false`，开启后框架默认会对已知三方依赖进行按需加载，项目的构建体验将进一步提升，内置三方依赖列表参考[代码](https://github.com/alibaba/ice/blob/1989fc18fa26230e91322e225dd20633d268a26b/packages/ice/src/config.ts#L364-L421)。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
参考配置：
|
|
|
|
|
|
```js
|
|
|
|
|
|
import { defineConfig } from '@ice/app';
|
|
|
|
|
|
|
|
|
|
|
|
export default defineConfig(() => ({
|
|
|
|
|
|
optimization: {
|
|
|
|
|
|
disableRouter: true,
|
|
|
|
|
|
// optimizePackageImport 配置为 true 则使用内置的三方依赖列表，如果配置为数组则会在内置列表基础上追加
|
|
|
|
|
|
optimizePackageImport: ['@ice/components'],
|
|
|
|
|
|
},
|
|
|
|
|
|
}));
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
2022-07-07 18:56:14 +08:00
|
|
|
|
> 如有定制需求欢迎👏 PR 或反馈：<https://github.com/alibaba/ice/issues>
|
