feat: enhance browser error log for undefined process.env

e2e/cases/diagnostic/process-undefined/index.test.ts

@@ -0,0 +1,11 @@
+import { rspackTest } from '@e2e/helper';
+
+rspackTest(
+  'should print help message if undefined process.env.* is accessed in dev',
+  async ({ dev }) => {
+    const rsbuild = await dev();
+    await rsbuild.expectLog(
+      'To access `process.env.*`, define them in a `.env` file with the `PUBLIC_` prefix.',
+    );
+  },
+);

e2e/cases/diagnostic/process-undefined/src/index.js

@@ -0,0 +1 @@
+console.log(process.env.UNDEFINED_VALUE);

packages/core/src/helpers/format.ts

@@ -88,7 +88,7 @@ function hintUnknownFiles(message: string): string {
       `@rsbuild/plugin-${packageName}`,
     )}" ${color.dim(
       `(https://npmjs.com/package/@rsbuild/plugin-${packageName})`,
-    )}.`;
+    )}.\n`;
   };
 
   const recommendPlugins = [

packages/core/src/server/browserLogs.ts

@@ -109,6 +109,20 @@ const formatErrorLocation = async (
   return rawLocation;
 };
 
+const enhanceBrowserErrorLog = (log: string) => {
+  const isProcessUndefined = log.includes(
+    'ReferenceError: process is not defined',
+  );
+  if (isProcessUndefined) {
+    return `${log}\n${color.yellow(`        - \`process\` is a Node.js global and not available in browsers.
+        - To access \`process.env.*\`, define them in a \`.env\` file with the \`PUBLIC_\` prefix.
+        - Or configure them via \`source.define\`.
+        - Alternatively, install \`@rsbuild/plugin-node-polyfill\` to polyfill Node.js globals.`)}`;
+  }
+
+  return log;
+};
+
 /**
  * Formats error messages received from the browser into a log string with
  * source location information.
@@ -127,5 +141,5 @@ export const formatBrowserErrorLog = async (
     }
   }
 
-  return log;
+  return enhanceBrowserErrorLog(log);
 };