diff --git a/docs/config/task-options.md b/docs/config/task-options.md index 4062647..9e3551f 100644 --- a/docs/config/task-options.md +++ b/docs/config/task-options.md @@ -52,17 +52,10 @@ - **类型：** `object` 转译配置项。 + - HTML模板引擎 配置项，请参见 [这里](../guide/task-html#configuration) - CSS预处理器 配置项，请参见 [这里](../guide/task-style#configuration) -- `babel` 配置项，请参见 [这里](../guide/task-script#configuration) - -## module {#module} -- **类型：** `boolean` -- **默认：** `false` - -Javascript 文件是否模块化。 -当项目中的JS文件使用了 `require` 或 `import` 语句时，请启用模块化。 ## minify {#minify} - **类型：** `boolean | MinifyOptions` diff --git a/docs/guide/build.md b/docs/guide/build.md index a7ed6fd..4a810b9 100644 --- a/docs/guide/build.md +++ b/docs/guide/build.md @@ -7,7 +7,7 @@ ### browserslist -通过 `pipflow create` 创建的项目，在项目根目录下有一个单独的 `browserslistrc` 文件，用于指定项目支持的浏览器范围。你也可以在 `package.json` 文件里配置 `browserslist` 字段。 +通过 `pipflow create` 创建的项目，在项目根目录下有一个单独的 `.browserslistrc` 文件，用于指定项目支持的浏览器范围。你也可以在 `package.json` 文件里配置 `browserslist` 字段。 这个值会被 `@babel/preset-env` 和 `postcss-preset-env` 用来确定需要转译的 JavaScript 特性和需要添加的 CSS 浏览器前缀。 @@ -16,5 +16,65 @@ ### Polyfill -请注意，默认情况下 Vite 只处理语法转译，且 不包含任何 polyfill。你可以前往 Polyfill.io 查看，这是一个基于用户浏览器 User-Agent 字符串自动生成 polyfill 包的服务。 +一个基于 pipflow CLI 创建的项目，它通过 `@babel/preset-env` 和 `browserslist` 配置来决定项目需要的 polyfill。 +默认情况下，babel.config.js 预设 `useBuiltIns: "usage"`，这样它会根据源代码中出现的语言特性自动检测需要的 polyfill。这确保了最终包里 polyfill 数量的最小化。然而，这也意味着如果其中一个依赖需要特殊的 polyfill，默认情况下 Babel 无法将其检测出来。 + +你可以通过修改项目中的 babel.config.js 配置来自行调整 polyfill。 + +::: tip 温馨提示 +我们推荐以这种方式添加 polyfill 而不是在源代码中直接导入它们，因为如果这里列出的 polyfill 在 browserslist 的目标中不需要，则它会被自动排除。 +::: + + +## 自定义构建 + +构建生产环境应用程序包默认是通过 `pipflow build` 命令来完成的。如果在未修改配置文件 `pipflow.config.js` 的 `tasks` 选项时，其构建过程任务如下： + +``` +└─┬ build + └─┬ + ├── del:dest + ├─┬ + │ ├── copy:public + │ └── static:4 + ├─┬ + │ ├── script:2 + │ └── style:3 + └─┬ + └── html:1 +``` + +如果你想自定义构建流程，你可以创建一个 `compose` 类型的组合任务，配置自定义构建流程。 详细配置请参见 [这里](./task-user.md#compose-task)。 + +当配置完成之后，运行下面命令即可构建生产环境应用程序包： + +```bash +pipflow task --mode=production +``` +> 注: `` 代指你的组合任务名称。 + + +你可以将 `package.json` 中的 `scripts` 字段的 `build` 命令更改为: + +```json +{ + "scripts": { + "dev": "pipflow dev", + "build": "pipflow build", // [!code --] + "build": "pipflow task --mode=production", // [!code ++] + "preview": "pipflow task server --preview" + } +} +``` + +然后运行 `npm run build` 即可。 + +::: warning 提醒 +自定义 `build` 命令必须使用 `--mode=production` 参数。 如果要构建 `mode` 不为 `production` 的其他平台环境的部署包，请在命令开头加上 `cross-env NODE_ENV=production` (确保构建主机的环境变量 `NODE_ENV` 为 `production`)。 + +完整命令如下： +``` +cross-env NODE_ENV=production pipflow task --mode=staging +``` +::: diff --git a/docs/guide/cli.md b/docs/guide/cli.md index c3b02eb..f40c1c7 100644 --- a/docs/guide/cli.md +++ b/docs/guide/cli.md @@ -55,9 +55,13 @@ Options: 如果你在创建项目时，拉取模板源码一直处于 loading 状态 或者超时失败，建议从 `gitee` 拉取模板，但是本地一定要安装 git 环境。 运行以下命令创建新项目： + `pipflow create my-project --repo=gitee --clone` ::: +> 吐槽：gitee 真不想评价，除去不可抗拒因素外，自身也是一塌糊涂，不求上进的xx! + + ### 项目目录结构 diff --git a/docs/guide/task-assets.md b/docs/guide/task-assets.md index 8ea8a71..240adb9 100644 --- a/docs/guide/task-assets.md +++ b/docs/guide/task-assets.md @@ -1,7 +1,11 @@ # 静态资源 +## 静态文件任务 -## 图片压缩 + +## 图片任务 + +### 图片压缩 由于图片压缩是一个耗时任务，且 `gulp-imagemin` 插件**安装依赖经常失败**(国内环境)。鉴于此会影响整个工程的安装运行，所以 `pipflow` 并未内置图片压缩功能，如果需要则手动安装依赖并引入插件即可。 diff --git a/docs/guide/task-html.md b/docs/guide/task-html.md index b766b58..0221602 100644 --- a/docs/guide/task-html.md +++ b/docs/guide/task-html.md @@ -2,18 +2,12 @@ ## 处理流程 {#process-flow} -* 环境变量处理 - > 环境变量在构建时会被静态替换 -* 模板渲染 - > 渲染HTML模板引擎，支持 `Pug`, `EJS`, `Handlebars`, `Nunjucks`, `art-template` -* 别名替换 - > 静态替换 `alias` 对应的字符串 -* 自定义处理流程 - > 处理 `pipflow.config.js` 中添加的自定义 `plugins` -* 内容压缩 - > 基于 `html-minifier-terser` 的内容压缩 -* 资源文件指纹 - > 将构建后通过生成的 `manifest.json` 中包含 hash 过的资源文件版本的映射，进行引入链接的替换 +- 环境变量处理 - 环境变量在构建时会被静态替换 +- 模板渲染 - 渲染HTML模板引擎，支持 `Pug`, `EJS`, `Handlebars`, `Nunjucks`, `art-template` +- 别名替换 - 静态替换 `alias` 对应的字符串 +- 自定义处理流程 - 处理 `pipflow.config.js` 中添加的自定义 `plugins` +- 内容压缩 - 基于 `html-minifier-terser` 的内容压缩 +- 资源文件指纹 - 将构建后通过生成的 `manifest.json` 中包含 hash 过的资源文件版本的映射，进行引入链接的替换 ## 环境变量处理 @@ -47,7 +41,7 @@ html内容中的以 `process.env.XXX` 写入的环境变量将会被静态替换 - **文档:** [art-template文档](https://aui.github.io/art-template/) 、 [gulp-art-tpl 插件文档](https://www.npmjs.com/package/gulp-art-tpl) - *个人推荐*： 功能强大，使用简单 -这些模板引擎在过去曾经很流行，每一款都有自己独特的特点和用法。您可以根据自己的需求和偏好选择适合的模板引擎来开发您的项目。 +这些模板引擎在过去都很流行，每一款都有自己独特的特点和用法。您可以根据自己的需求和偏好选择适合的模板引擎来开发您的项目。 ### 渲染配置项 {#configuration} @@ -118,4 +112,5 @@ html的压缩是基于 `html-minifier-terser` 插件, 详细配置请参见 [这 } ``` +你可以通过 `build.htmlMinify` 配置项来指定压缩选项。 参见 [这里](../config/build-options.md#build-htmlminify)。 diff --git a/docs/guide/task-script.md b/docs/guide/task-script.md index 5186430..2ee03a7 100644 --- a/docs/guide/task-script.md +++ b/docs/guide/task-script.md @@ -3,34 +3,27 @@ ## 处理流程 {#process-flow} -* 设置变量处理 - > 环境变量注入 -* 别名替换 - > 静态替换 `alias` 对应的字符串 -* 自定义处理流程 - > 处理 `pipflow.config.js` 中添加的自定义 `plugins` -* babel转译 - > babel 转译 -* 压缩处理 - > 基于 `terser` 压缩混淆 -* 源码映射 sourcemap - > 生成 source map 文件 -* 文件指纹 - > 生成文件hash, 支持 `[name]-[hash]` 和 `[name]?[hash]` 两种方式。 +- 环境变量处理 - 环境变量注入 +- 别名替换 - 静态替换 `alias` 对应的字符串 +- 自定义处理流程 - 处理 `pipflow.config.js` 中添加的自定义 `plugins` +- babel转译 +- 压缩混淆 - 基于 `terser` 压缩混淆 +- 生成 source map 文件 +- 生成文件hash - 支持 `[name]-[hash]` 和 `[name]?[hash]` 两种方式。 ## 文件入口 文件入口配置支持 单一字符串，数组，和对象 3 种方式。 -1. 单一通配符 +### 1. 字符串通配符 ```js { input: './src/scripts/**/*.{js,mjs}' } ``` -2. 数组通配符 +### 2. 数组方式 ```js { input: [ @@ -41,7 +34,7 @@ } ``` -3. 对象方式 +### 3. 对象方式 ```js { input: { @@ -63,9 +56,16 @@ dist/scripts/pages.js ``` -## babel转译 +## babel 转译 +如果开启 `babel` 转译，则使用 `webpack` 进行 Javascript 构建。 -## module配置 +你可以通过修改项目中的 `babel.config.js` 文件来配置 babel 的转译选项。或者调整 `.browserslistrc` 修改支持的目标浏览器。 +## terser + +Javascript 文件是基于 `terser` 进行压缩混淆，配置项请点 [这里](../config/build-options.md#build-jsminify)。 + +具体配置可以查阅 [terser](https://github.com/terser/terser)。 + diff --git a/docs/guide/task-user.md b/docs/guide/task-user.md index badd832..eda17e5 100644 --- a/docs/guide/task-user.md +++ b/docs/guide/task-user.md @@ -1,6 +1,6 @@ # 自定义任务和流程 - +## 扩展任务 {#extend-task} 示例： @@ -20,3 +20,10 @@ module.exports = defineConfig({ ] }) ``` + +## 创建新任务 {#create-task} + + +## 组合任务 {#compose-task} + +