Node.js与浏览器不兼容的原因解析及相关细节、资源请求

Great question—this is a super common pain point when switching between browser and Node.js environments, so let’s unpack it step by step.

The core incompatibilities boil down to two big areas: module systems and runtime environment APIs/globals:

• Module system differences:

  • Node.js was built before browsers had a standardized module system. It adopted CommonJS (using require() and module.exports) as its default way to handle code modularization.
  • Browsers originally relied on global scope pollution via <script> tags, and later adopted ES Modules (ESM) (using import/export) as the official standard. These two systems have different loading behaviors (synchronous vs. asynchronous) and syntax rules.
  • This mismatch is exactly why node_modules and package.json exist: Node needs a way to resolve and store CommonJS dependencies that browsers wouldn’t natively understand.

• Runtime environment differences:

  • Browsers run in a client-side context, so they expose global objects like window, document, navigator, and APIs for DOM manipulation, fetching remote resources, etc.
  • Node.js runs on the server, so it exposes global objects like global (now globalThis for cross-environment consistency), plus APIs for file system access (fs), process management (process), network servers (http), etc.—tools that make no sense in a browser.

It all comes down to different design goals and historical timing:

1. Timing: When Node.js launched in 2009, browsers had no native module system. The team behind Node needed a way to enable modular server-side code quickly, so they adopted the existing CommonJS spec (which was already used in server-side JS projects).
2. Use case priorities:
   • Node.js is built for server-side execution, where synchronous module loading (a key feature of CommonJS) is acceptable—modules are loaded once at startup, so there’s no performance hit for blocking I/O during initialization.
   • Browsers prioritize fast page loads, so ESM was designed to support asynchronous, non-blocking loading of modules over the network.
3. Environment-specific needs: Browsers don’t need access to a server’s file system or process manager, just as Node.js has no need for DOM manipulation tools. These divergent needs led to separate API sets.

Let’s look at concrete examples to make this tangible:

Module Loading Syntax #

• Node.js (CommonJS):

  // Import a core module
  const fs = require('fs');
  // Export a function
  module.exports = function greet() { console.log('Hello!') };
  

• Browser (ESM):

  <script type="module">
    // Import a local module (must include full relative path)
    import { greet } from './utils.js';
    // Export a variable
    export const message = 'Hi there!';
  </script>
  

  Note: Browsers won’t recognize require(), and Node.js won’t parse import/export by default (you need to use .mjs files or set "type": "module" in package.json).

Global Object Differences #

• In a browser’s global scope:

  console.log(this === window); // true
  console.log(document); // Accesses the DOM tree
  

• In Node.js:

  console.log(this === module.exports); // true (in a module)
  console.log(global.process); // Accesses the current Node process
  console.log(document); // Throws a ReferenceError—no DOM here!
  

Tools to Bridge the Gap #

To make code work across both environments, developers use tools like:

• Webpack/Rollup: Bundles Node.js/ESM code into browser-compatible bundles that handle module resolution and polyfill missing APIs.
• Browserify: Converts CommonJS modules into code that runs in browsers.
• Node.js ESM support: Node now fully supports ESM, so you can write code that matches browser syntax (with a few caveats like file extensions in imports).

内容的提问来源于stack exchange，提问作者325