docs: clarify import.meta.env define behavior

Author: intellild

packages/rspack/src/builtin-plugin/DefinePlugin.ts

@@ -6,9 +6,7 @@ import WebpackError from '../lib/WebpackError';
 const IMPORT_META_ENV_KEY = 'import.meta.env';
 const IGNORED_IMPORT_META_ENV = Symbol('ignored import.meta.env');
 
-export type DefinePluginOptions = Record<string, CodeValue> & {
-  'import.meta.env'?: ImportMetaEnvCodeValue;
-};
+export type DefinePluginOptions = Record<string, CodeValue>;
 export const DefinePlugin = create(
   BuiltinPluginName.DefinePlugin,
   function (define: DefinePluginOptions): NormalizedCodeValue {
@@ -155,7 +153,6 @@ const isImportMetaEnvObject = (
   !(value instanceof RegExp);
 
 type CodeValue = RecursiveArrayOrRecord<CodeValuePrimitive>;
-type ImportMetaEnvCodeValue = string | Record<string, CodeValue>;
 type CodeValuePrimitive =
   null | undefined | RegExp | Function | string | number | boolean | bigint;
 type NormalizedCodeValuePrimitive = null | string | number | boolean;

website/docs/en/plugins/webpack/define-plugin.mdx

@@ -170,6 +170,9 @@ Rspack supports defining `import.meta.env` so that environment variables are rea
 
 ```js title="rspack.config.mjs"
 export default {
+  experiments: {
+    env: true,
+  },
   plugins: [
     new rspack.DefinePlugin({
       'import.meta.env': {
@@ -187,7 +190,7 @@ console.log(import.meta.env.MODE); // 'production'
 console.log(import.meta.env.NOT_EXIST); // undefined
 ```
 
-You usually do not write this `DefinePlugin` by hand. [`EnvironmentPlugin`](/plugins/webpack/environment-plugin), `NODE_ENV`, and user `DefinePlugin` `import.meta.env.*` keys are collected into one accumulated env object and exposed as `import.meta.env` automatically. User `DefinePlugin` `process.env.*` keys keep their `process.env` behavior and are not collected into `import.meta.env`.
+When `experiments.env` is enabled, you usually do not write this `DefinePlugin` by hand. [`EnvironmentPlugin`](/plugins/webpack/environment-plugin), `NODE_ENV`, and user `DefinePlugin` `import.meta.env.*` keys are collected into one accumulated env object and exposed as `import.meta.env` automatically. User `DefinePlugin` `process.env.*` keys keep their `process.env` behavior and are not collected into `import.meta.env`.
 
 ## `process.env`
 
@@ -208,11 +211,11 @@ When the env object is accumulated (via [`EnvironmentPlugin`](/plugins/webpack/e
 
 ### Destructuring
 
-`process.env` destructuring is supported: when every destructured key is a defined env key, the destructuring source is inlined with only those keys.
+`process.env` destructuring is supported for corresponding `process.env.KEY` defines. When every destructured key has a matching `process.env.KEY` define, the destructuring source is inlined with only those keys.
 
 ```js title="src/index.js"
 const { NODE_ENV, MODE } = process.env;
 console.log(NODE_ENV, MODE);
 ```
 
-If any destructured key is not a defined env key, the access falls back to the runtime `process.env`, since it may legitimately hold that key at runtime.
+If any destructured key does not have a matching `process.env.KEY` define, the access falls back to the runtime `process.env`, since it may legitimately hold that key at runtime.

website/docs/zh/plugins/webpack/define-plugin.mdx

@@ -170,6 +170,9 @@ Rspack 支持定义 `import.meta.env`，使环境变量可以在 ESM 源码中
 
 ```js title="rspack.config.mjs"
 export default {
+  experiments: {
+    env: true,
+  },
   plugins: [
     new rspack.DefinePlugin({
       'import.meta.env': {
@@ -187,7 +190,7 @@ console.log(import.meta.env.MODE); // 'production'
 console.log(import.meta.env.NOT_EXIST); // undefined
 ```
 
-通常你不需要手写这个 `DefinePlugin`。[`EnvironmentPlugin`](/plugins/webpack/environment-plugin)、`NODE_ENV` 以及用户 `DefinePlugin` 中的 `import.meta.env.*` 键，会被收集到同一个累积的环境对象中，并自动以 `import.meta.env` 暴露。用户 `DefinePlugin` 中的 `process.env.*` 键会保持 `process.env` 的行为，不会被收集到 `import.meta.env`。
+启用 `experiments.env` 后，通常你不需要手写这个 `DefinePlugin`。[`EnvironmentPlugin`](/plugins/webpack/environment-plugin)、`NODE_ENV` 以及用户 `DefinePlugin` 中的 `import.meta.env.*` 键，会被收集到同一个累积的环境对象中，并自动以 `import.meta.env` 暴露。用户 `DefinePlugin` 中的 `process.env.*` 键会保持 `process.env` 的行为，不会被收集到 `import.meta.env`。
 
 ## `process.env`
 
@@ -208,11 +211,11 @@ console.log(process.env.CUSTOM); // 运行时从运行时的 process.env 解析
 
 ### 解构
 
-`process.env` 支持解构：当解构的每个 key 都是已定义的环境变量 key 时，解构源会被内联为仅含这些 key 的对象。
+`process.env` 支持对对应的 `process.env.KEY` define 生效的解构：当解构的每个 key 都有匹配的 `process.env.KEY` define 时，解构源会被内联为仅含这些 key 的对象。
 
 ```js title="src/index.js"
 const { NODE_ENV, MODE } = process.env;
 console.log(NODE_ENV, MODE);
 ```
 
-如果解构的某个 key 不是已定义的环境变量 key，则该访问会回退到运行时的 `process.env`，因为运行时它可能确实持有该 key。
+如果解构的某个 key 没有匹配的 `process.env.KEY` define，则该访问会回退到运行时的 `process.env`，因为运行时它可能确实持有该 key。