docs: 新功能配套文档

docs/config-detail.md

@@ -47,7 +47,7 @@ config = {
 
 `object`
 
-用于配置一些全局变量供代码中进行使用。
+用于配置一些全局变量供业务代码中进行使用。
 
 配置方式可参考 [Webpack DefinePlugin](https://webpack.js.org/plugins/define-plugin/)，例如：
 
@@ -146,7 +146,12 @@ module.exports = {
 }
 ```
 
-这样就能在代码中通过 `process.env.NODE_ENV === 'development'` 来判断环境。
+这样就能在业务代码中通过 `process.env.NODE_ENV === 'development'` 来判断环境。
+
+:::warning 注意
+这里的配置的环境变量只能在 `业务代码` 中使用，无法在 `node环境` 代码中获取到其配置的值， 也不会改变 `node环境` 中 `process.env.NODE_ENV` 的值。
+配置环境变量更推荐使用 [模式和环境变量](./env-mode-config.md)
+:::
 
 ## copy
 

docs/config.md

@@ -2,15 +2,17 @@
 title: 编译配置
 ---
 
-编译配置存放于项目根目录下的 `config` 目录中，包含三个文件：
+编译配置存放于项目根目录下的 `config` 目录中，只要确保 `config/index.js` 或者 `config/index.ts` 文件存在，可以作为用户自定义编译配置导出即可。你也可以选择拆分成三个文件（具体见默认配置）：
 
 - `index.js` 是通用配置
 - `dev.js` 是项目预览时的配置
 - `prod.js` 是项目打包时的配置
 
 详细的编译配置文档请查阅：[编译配置详情](./config-detail)
 
-### 默认配置
+> 从 Taro v3.6.5 开始， `config/index.ts` 支持使用 `ts` 文件(`react native` 暂不支持)
+
+## 默认配置
 
 ```js title="config/index.js"
 const config = {
@@ -94,3 +96,77 @@ module.exports = function (merge) {
   return merge({}, config, require('./prod'))
 }
 ```
+
+## defineConfig 辅助函数
+
+:::info
+Taro v3.6.9 开始支持
+
+react native 暂不支持
+:::
+
+开发者可以导入 `defineConfig` 函数包裹配置对象， 以获得 类型提示 和 自动补全.
+
+### 基础配置
+
+```ts
+// config/index.ts
+import { defineConfig } from '@tarojs/cli'
+
+export default defineConfig({
+  // ...Taro 配置
+})
+```
+
+同时 `config/index.ts` 支持直接导出对象：
+
+```ts
+// 直接导出对象
+import type { UserConfigExport } from '@tarojs/cli'
+
+export default {
+  // ...Taro 配置
+} satisfies UserConfigExport
+```
+
+### 异步配置
+
+如果配置需要调用一个异步函数，也可以转而导出一个异步函数：
+
+```ts
+import { defineConfig } from '@tarojs/cli'
+
+export default defineConfig(async (mergin, { command, mode }) => {
+  const data = await asyncFunction()
+  return {
+    // Taro 配置
+  }
+})
+```
+
+### 情景配置
+
+如果配置文件需要基于 命令 或者不同的 [模式](./env-mode-config.md) 来决定选项，则可以选择导出这样一个函数：
+
+```ts
+import { defineConfig } from '@tarojs/cli'
+
+export default defineConfig((mergin, { command, mode }) => {
+  // mergin 为webpack-mergin, 兼容以前的配置
+  // 假如执行的命令为: "taro build --type weapp --mode test"
+  // 则 command 的值为 build, mode 的值为 test
+  if (mode === 'development') {
+    return {
+      // dev 独有配置
+    }
+  } else if (mode === 'test') {
+    return {
+      // test 独有配置
+    }
+  } else {
+    return {
+      // build 独有配置
+    }
+  }
+})
+```

docs/env-mode-config.md

@@ -0,0 +1,108 @@
+---
+title: 模式和环境变量
+---
+
+:::info
+Taro v3.5.10 开始支持，之前的版本可参考 [taro-plugin-environment](https://github.com/bigmeow/taro-plugin-environment)
+:::
+
+`模式` 在 `Taro cli` 中，是用于给环境变量分组并加载其分组下的环境变量，它是一组环境变量的 `name`。
+它参考了 [vue-cli 中的模式和环境变量加载方式](https://cli.vuejs.org/zh/guide/mode-and-env.html) , 所以若你之前使用过 `vue-cli`，可以更快掌握用法。
+
+## 默认行为
+
+默认情况下, `模式` `Taro cli` 有 2 个模式：
+
+- `development` 模式用于开发时 `taro build --type weapp --watch`，它等价于 `taro build --type weapp --watch --mode development`
+- `production` 模式用于生产时 `taro build --type weapp`， ，它等价于 `taro build --type weapp --mode production`
+
+可以发现，默认情况下 `模式` 的值，取决于 `NODE_ENV` 的值（但是反过来说模式的值无法改变 `NODE_ENV` 的值）。
+
+假设你有`开发`和`生产`2 个环境，你可以在项目根目录下新建两个`env`环境文件：
+
+```
+env.development     # 在 development 模式时被载入
+env.production      # 在 production 模式时被载入
+```
+
+环境文件只包含环境变量的“键=值”对：
+
+```
+TARO_APP_API="https://api.tarojs.com"
+```
+
+:::warning 限制
+请注意，只有以 `TARO_APP_` 开头的变量将通过 `webpack.DefinePlugin` 静态地嵌入到客户端侧的代码中。这是为了避免和系统内置环境变量冲突。
+:::
+
+被载入的环境变量我们可以在所有 `taro` 插件、 `config/index.ts`配置文件 以及 `src` 目录下面的项目文件中使用, 例如：
+
+```ts
+// src/service/request.ts
+const request = axios.create({
+  baseURL: process.env.TARO_APP_API
+};
+export default request
+```
+
+在构建过程中，`process.env.TARO_APP_API` 将会被相应的值所取代。在 `TARO_APP_API="https://api.tarojs.com"` 的情况下，它会被替换为 "https://api.tarojs.com"
+
+## 自定义模式
+
+若默认的模式满足不了需求，你可以在命令上使用参数 `--mode 模式名` 的方式来指定模式名，以加载某一组环境变量，例如：
+
+```bash
+taro build --type weapp --mode uat
+```
+
+以上命令表示在构建时会加载 `.env.uat` 文件中的环境变量.
+
+mode 具体载入规则：
+
+```sh
+.env                # 在所有的环境中被载入
+.env.local          # 在所有的环境中被载入，但会被 git 忽略
+.env.[mode]         # 只在指定的模式中被载入
+.env.[mode].local   # 只在指定的模式中被载入，但会被 git 忽略
+```
+
+:::info 环境文件加载优先级
+
+为一个特定模式准备的环境文件 (例如 .env.production) 将会比一般的环境文件 (例如 .env) 拥有更高的优先级。
+
+.env 环境文件是通过运行 `taro` 命令载入的，因此环境文件发生变化，你需要重启服务。
+:::
+
+## 只在本地有效的变量
+
+有的时候你可能有一些不应该提交到代码仓库中的变量，尤其是当你的项目托管在公共仓库时。这种情况下你应该使用一个 `.env.local` 文件取而代之。本地环境文件默认会被忽略，且出现在 `.gitignore` 中。
+
+`.local` 也可以加在指定模式的环境文件上，比如 `.env.development.local` 将会在 `development` 模式下被载入，且被 `git` 忽略。
+
+## 自定义环境变量前缀
+
+前面提到，默认只加载 `.env` 文件中以 `TARO_APP_` 前缀开头的环境变量，你可能想改成自己公司的英文名称作为前缀，`@tarojs/cli` 提供了 `--env-prefix` 参数来实现这一需求：
+
+```sh
+taro build --type weapp --mode development --env-prefix JD_APP_
+```
+
+此时 `.env` 文件中能被加载的环境变量只能是 `JD_APP_` 前缀开头的：
+
+```
+TARO_APP_API="https://api.tarojs.com"    # 不满足前缀，不加载
+
+JD_APP_TEST="foo"                        # 满足前缀，加载
+```
+
+但是，有个特殊的环境变量不受自定义前缀配置的影响，始终会被加载，那就是 `TARO_APP_ID`。
+
+## 特殊环境变量 `TARO_APP_ID`
+
+:::info
+Taro v3.6.9 开始支持
+:::
+
+`TARO_APP_ID` 是专门针对小程序的 `appid` 设计的，在构建输出 `dist/project.config.json` 文件前， 会将 `dist/project.config.json` 文件中的 `appid` 字段，修改为 `TARO_APP_ID` 的值。 在不同环境配置不同的小程序 `appid` 时，它特别有用，还能免去开发者在开发者工具上手动修改 `appid` 的麻烦。
+
+![免去开发者工具修改appid](@site/static/img/update-appid.png)

docs/request.md

@@ -51,11 +51,17 @@ export request;
 
 ## 限制
 
+:::danger 限制
+
 - 暂不支持上传，且插件默认会将全局 `FormData` 、 `Blob` 对象替换成 `undefined`（仅针对小程序环境）
 - 本插件需搭配 taro 主包 3.6.0 及其以上版本使用
 - webpack4 用户需升级插件版本为 `3.6.6` 及其以上
 
+:::
+
 ## 插件发布记录
 
 - `3.6.0` 插件首次发布
 - `3.6.6` [fix: @tarojs/plugin-http 对 webpack4 的兼容](https://github.com/NervJS/taro/pull/13699)
+- `3.6.7` 优化事件属性的实现， [#13824](https://github.com/NervJS/taro/issues/13824)
+- `3.6.8` 修复发送请求时未正确携带包含 `httpOnly` 的 `cookie` 的问题，[#13941](https://github.com/NervJS/taro/issues/13941)

sidebars.js

@@ -17,7 +17,7 @@ module.exports = {
       {
         label: '配置',
         type: 'category',
-        items: ['config', 'size', 'app-config', 'page-config', 'project-config', 'babel-config'],
+        items: ['env-mode-config', 'config', 'size', 'app-config', 'page-config', 'project-config', 'babel-config'],
       },
       {
         label: 'React',

static/css/custom.css

@@ -20,6 +20,10 @@ main > .container {
   max-width: none;
 }
 
+main > .container p {
+  line-height: 1.5;
+}
+
 main > .container > .row {
   margin: 0;
 }

versioned_docs/version-3.x/config-detail.md

@@ -47,7 +47,7 @@ config = {
 
 `object`
 
-用于配置一些全局变量供代码中进行使用。
+用于配置一些全局变量供业务代码中进行使用。
 
 配置方式可参考 [Webpack DefinePlugin](https://webpack.js.org/plugins/define-plugin/)，例如：
 
@@ -146,7 +146,12 @@ module.exports = {
 }
 ```
 
-这样就能在代码中通过 `process.env.NODE_ENV === 'development'` 来判断环境。
+这样就能在业务代码中通过 `process.env.NODE_ENV === 'development'` 来判断环境。
+
+:::warning 注意
+这里的配置的环境变量只能在 `业务代码` 中使用，无法在 `node环境` 代码中获取到其配置的值， 也不会改变 `node环境` 中 `process.env.NODE_ENV` 的值。
+配置环境变量更推荐使用 [模式和环境变量](./env-mode-config.md)
+:::
 
 ## copy
 

versioned_docs/version-3.x/config.md

@@ -2,15 +2,17 @@
 title: 编译配置
 ---
 
-编译配置存放于项目根目录下的 `config` 目录中，包含三个文件：
+编译配置存放于项目根目录下的 `config` 目录中，只要确保 `config/index.js` 或者 `config/index.ts` 文件存在，可以作为用户自定义编译配置导出即可。你也可以选择拆分成三个文件（具体见默认配置）：
 
 - `index.js` 是通用配置
 - `dev.js` 是项目预览时的配置
 - `prod.js` 是项目打包时的配置
 
 详细的编译配置文档请查阅：[编译配置详情](./config-detail)
 
-### 默认配置
+> 从 Taro v3.6.5 开始， `config/index.ts` 支持使用 `ts` 文件(`react native` 暂不支持)
+
+## 默认配置
 
 ```js title="config/index.js"
 const config = {
@@ -94,3 +96,77 @@ module.exports = function (merge) {
   return merge({}, config, require('./prod'))
 }
 ```
+
+## defineConfig 辅助函数
+
+:::info
+Taro v3.6.9 开始支持
+
+react native 暂不支持
+:::
+
+开发者可以导入 `defineConfig` 函数包裹配置对象， 以获得 类型提示 和 自动补全.
+
+### 基础配置
+
+```ts
+// config/index.ts
+import { defineConfig } from '@tarojs/cli'
+
+export default defineConfig({
+  // ...Taro 配置
+})
+```
+
+同时 `config/index.ts` 支持直接导出对象：
+
+```ts
+// 直接导出对象
+import type { UserConfigExport } from '@tarojs/cli'
+
+export default {
+  // ...Taro 配置
+} satisfies UserConfigExport
+```
+
+### 异步配置
+
+如果配置需要调用一个异步函数，也可以转而导出一个异步函数：
+
+```ts
+import { defineConfig } from '@tarojs/cli'
+
+export default defineConfig(async (mergin, { command, mode }) => {
+  const data = await asyncFunction()
+  return {
+    // Taro 配置
+  }
+})
+```
+
+### 情景配置
+
+如果配置文件需要基于 命令 或者不同的 [模式](./env-mode-config.md) 来决定选项，则可以选择导出这样一个函数：
+
+```ts
+import { defineConfig } from '@tarojs/cli'
+
+export default defineConfig((mergin, { command, mode }) => {
+  // mergin 为webpack-mergin, 兼容以前的配置
+  // 假如执行的命令为: "taro build --type weapp --mode test"
+  // 则 command 的值为 build, mode 的值为 test
+  if (mode === 'development') {
+    return {
+      // dev 独有配置
+    }
+  } else if (mode === 'test') {
+    return {
+      // test 独有配置
+    }
+  } else {
+    return {
+      // build 独有配置
+    }
+  }
+})
+```