JavaScript 模块化与工程化

<!-- a.js -->
<script>
  var name = 'Alice';
  function greet() {
    console.log('Hello, ' + name);
  }
</script>

<!-- b.js -->
<script>
  var name = 'Bob'; // 覆盖了 Alice！
  function greet() {
    console.log('Hi, ' + name);
  }
</script>

// namespace.js
var MyApp = {
  config: { apiUrl: '/api' },
  utils: {
    formatDate: function (date) {
      return date.toISOString().slice(0, 10);
    },
  },
  models: {},
  views: {},
};

// 使用
MyApp.utils.formatDate(new Date()); // '2024-09-04'

var Counter = (function () {
  var count = 0;
  function increment() {
    count++;
  }
  function decrement() {
    count--;
  }
  function getValue() {
    return count;
  }
  // 在 return 时选择暴露哪些
  return {
    increment: increment,
    decrement: decrement,
    getValue: getValue,
  };
})();

// 定义模块 — define(id?, dependencies?, factory)
define('math', ['dependency'], function (dep) {
  function add(a, b) {
    return a + b;
  }
  function subtract(a, b) {
    return a - b;
  }
  return { add: add, subtract: subtract };
});

// 使用模块
require(['math'], function (math) {
  console.log(math.add(2, 3)); // 5
});

// math.js
const add = (a, b) => a + b;
const subtract = (a, b) => a - b;
module.exports = { add, subtract };

// app.js
const math = require('./math');
console.log(math.add(2, 3)); // 5

// umd-module.js
(function (root, factory) {
  if (typeof define === 'function' && define.amd) {
    // AMD (RequireJS)
    define(['lodash'], factory);
  } else if (typeof module === 'object' && module.exports) {
    // CommonJS (Node.js)
    module.exports = factory(require('lodash'));
  } else {
    // 浏览器全局变量
    root.MyModule = factory(root._);
  }
})(this, function (_) {
  var myModule = {
    sayHello: function (name) {
      return 'Hello, ' + name;
    },
    toUpper: function (str) {
      return _.toUpper(str);
    },
  };
  return myModule;
});

// ----- greeter.js -----
function greet(name) {
  return `Hello, ${name}!`;
}

const version = '1.0.0';

// 方式一：给 module.exports 赋值
module.exports = {
  greet: greet,
  version: version,
};

// 方式二：给 exports 添加属性
// exports.greet = greet;
// exports.version = version;

// 注意：不能直接 exports = { ... }，这会切断 exports 与 module.exports 的引用关系
// 以下写法是**错误**的：
// exports = { greet, version }; // ❌ — 不会导出任何内容

// ----- app.js -----
const greeter = require('./greeter');
console.log(greeter.greet('Alice')); // Hello, Alice!
console.log(greeter.version);         // 1.0.0

// 等价
exports.a = 1;
module.exports.a = 1;

// 不等价
exports = { a: 1 };  // ❌ module.exports 仍然是 {}
module.exports = { a: 1 }; // ✅

// ----- timer.js -----
console.log('Timer module is loading...');
const start = Date.now();

function elapsed() {
  return Date.now() - start;
}

module.exports = { elapsed };

// ----- main.js -----
console.log('Before require');
const timer = require('./timer'); // 同步阻塞，直到 timer.js 执行完毕
console.log('After require');
console.log(timer.elapsed()); // 毫秒数

Before require
Timer module is loading...
After require
0 （或很小的数值）

// ----- counter.js -----
let count = 0;
module.exports = {
  increment: () => ++count,
  getCount: () => count,
};

// ----- cache-demo.js -----
const c1 = require('./counter');
const c2 = require('./counter'); // 从缓存中取，不重新执行

c1.increment(); // count = 1
c1.increment(); // count = 2

console.log(c2.getCount()); // 2 — 因为 c1 和 c2 指向同一个模块实例
console.log(c1 === c2);     // true

// ----- a.js -----
console.log('a.js 开始执行');
const b = require('./b');
console.log('a.js 中, b.done =', b.done);
exports.done = true;
console.log('a.js 执行完毕');

// ----- b.js -----
console.log('b.js 开始执行');
const a = require('./a');
console.log('b.js 中, a.done =', a.done);
exports.done = true;
console.log('b.js 执行完毕');

// ----- main.js -----
console.log('main.js 开始');
const a = require('./a');
console.log('main.js 中, a.done =', a.done);

main.js 开始
a.js 开始执行
b.js 开始执行
b.js 中, a.done = undefined  ← 关键！a 还没执行完，只能拿到部分导出的对象
b.js 执行完毕
a.js 中, b.done = true
a.js 执行完毕
main.js 中, a.done = true

// ----- cjs-module.cjs -----
module.exports = {
  name: 'CommonJS Module',
  greet(name) {
    return `Hi, ${name}`;
  },
};

// ----- esm-module.mjs -----
import cjsModule from './cjs-module.cjs';
// 或者命名空间导入
import * as cjsNS from './cjs-module.cjs';

console.log(cjsModule.name);  // CommonJS Module
console.log(cjsModule.greet('Alice')); // Hi, Alice

// ----- esm-module.mjs -----
export const name = 'ES Module';
export function greet(name) {
  return `Hello, ${name}`;
}

// ----- cjs-app.cjs -----
async function main() {
  const esm = await import('./esm-module.mjs');
  console.log(esm.name);          // ES Module
  console.log(esm.greet('Bob'));  // Hello, Bob
}
main();

// ----- math.js -----
// 方式一：声明时直接导出
export const PI = 3.14159;
export function add(a, b) {
  return a + b;
}
export class Calculator {
  multiply(a, b) {
    return a * b;
  }
}

// 方式二：声明后统一导出
const E = 2.71828;
function subtract(a, b) {
  return a - b;
}
export { E, subtract };

// 方式三：重命名导出
function internalFn() {}
export { internalFn as publicFn };

// ----- logger.js -----
export default function log(message) {
  console.log(`[LOG] ${message}`);
}

// 也可以导出对象/类
export default class Logger {
  info(msg) {
    console.log(`[INFO] ${msg}`);
  }
}

// 或混合
const version = '1.0';
export default version;
export const author = 'Alice';

// ----- utils/index.js -----
// 直接聚合导出（不引入当前作用域）
export { default as formatDate } from './formatDate';
export { validateEmail } from './validate';
export { isNumeric } from './isNumeric';

// 重新导出所有命名导出
export * from './stringUtils';

// 重新导出并排除某个
export * from './numbers';
export { add } from './math'; // 如果 numbers 中也有 add，这里会报冲突。可用 as 解决

// 导入特定命名
import { PI, add, Calculator } from './math';

// 导入并重命名
import { add as addNumbers } from './math';

// 导入所有命名（命名空间导入）
import * as math from './math';
console.log(math.PI);

// 导入默认 + 命名
import log, { author } from './logger';

import log from './logger';
import Logger from './logger';
import { default as log } from './logger'; // 等价

// ----- 按需加载模块 -----
async function loadChart() {
  try {
    const chartModule = await import('./charts/barChart.js');
    const chart = new chartModule.BarChart('#container');
    chart.render(data);
  } catch (err) {
    console.error('模块加载失败', err);
  }
}

// 或在事件回调中使用
button.addEventListener('click', async () => {
  const { showToast } = await import('./toast.js');
  showToast('加载成功！');
});

// ----- 获取当前模块 URL -----
console.log(import.meta.url);
// 浏览器: https://example.com/js/app.js
// Node.js: file:///home/user/project/src/app.js

// ----- Node.js 中获取当前文件路径 -----
import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// ----- import.meta.resolve (Stage 4) -----
// 解析模块标识符的绝对 URL，不实际加载
// const specifier = await import.meta.resolve('./utils.js');

// ✅ 正确 — 顶层作用域
import { add } from './math.js';

// ❌ 错误 — 不能在条件语句中
if (needMath) {
  import { add } from './math.js'; // SyntaxError
}

// ✅ 动态导入则用 import()
if (needMath) {
  const { add } = await import('./math.js');
}

// ❌ 错误 — 不能在函数中
function load() {
  export const x = 1; // SyntaxError
}

// ----- math.js -----
export function add(a, b) {
  return a + b;
}
export function subtract(a, b) {
  return a - b;
}
export function multiply(a, b) {
  return a * b;
}
export function divide(a, b) {
  return a / b;
}

// ----- app.js -----
import { add } from './math.js';
console.log(add(2, 3));

// package.json
{
  "sideEffects": [
    "*.css",
    "*.scss",
    "./src/polyfills.js"
  ]
}

// 在 ESM 中，以下行为都会报错
x = 10;                // ReferenceError: x is not defined
delete x;              // SyntaxError
function fn(a, a) {}   // SyntaxError: duplicate parameter
with (obj) { ... }     // SyntaxError

<!-- 作为入口模块 -->
<script type="module" src="/src/main.js"></script>

<!-- 内联模块 -->
<script type="module">
  import { createApp } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js';
  console.log('ES Module 已加载');
</script>

<!-- 常规 script vs module 对比 -->
<script src="lib.js"></script>                   <!-- 默认 defer=false，阻塞渲染 -->
<script type="module" src="app.js"></script>     <!-- 默认 defer，不阻塞渲染 -->

<script type="importmap">
{
  "imports": {
    "lodash": "https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js",
    "vue": "https://unpkg.com/vue@3/dist/vue.esm-browser.js"
  }
}
</script>
<script type="module">
  import _ from 'lodash';
  import { createApp } from 'vue';
  console.log(_.join(['Hello', 'World'], ' '));
</script>

{
  "name": "my-project",
  "type": "module",  // 所有 .js 文件视为 ESM
  "exports": {
    ".": "./src/index.js",
    "./utils": "./src/utils.js"
  }
}

import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log(__dirname); // 与 CJS 中的 __dirname 行为一致

// 只能在 ESM 模块中使用
const response = await fetch('https://api.example.com/config');
const config = await response.json();
export default config;

// 常用 plugins
const HtmlWebpackPlugin = require('html-webpack-plugin'); // 生成 HTML
const MiniCssExtractPlugin = require('mini-css-extract-plugin'); // 提取 CSS 文件
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin'); // 压缩 CSS
const { DefinePlugin } = require('webpack'); // 定义全局变量

new DefinePlugin({
  'process.env.API_URL': JSON.stringify('https://api.example.com'),
}),

// webpack.config.js (dev)
module.exports = {
  devServer: {
    hot: true,  // 启用 HMR
    port: 3000,
    historyApiFallback: true, // SPA 路由支持
  },
};

if (module.hot) {
  module.hot.accept('./component.js', () => {
    console.log('Component updated!');
    render(); // 重新渲染
  });
}

// esbuild 使用示例（CLI）
// $ esbuild src/index.js --bundle --outfile=dist/bundle.js --minify

// 编程式使用
const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: true,
  sourcemap: true,
  target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
  loader: {
    '.js': 'jsx',
    '.ts': 'ts',
    '.css': 'css',
  },
}).then(result => {
  console.log('构建成功！');
}).catch(() => process.exit(1));

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', {
      targets: {
        browsers: ['> 1%', 'last 2 versions', 'not dead'],
        // 或指定 Node.js 版本
        // node: '14',
      },
      useBuiltIns: 'usage',    // 按需引入 polyfill
      corejs: 3,               // core-js 版本
      modules: false,          // 保留 ES Module 语法（让 Webpack 做 Tree Shaking）
    }],
  ],
  plugins: [
    // 如果有需要，添加单独插件
    '@babel/plugin-transform-runtime', // 复用辅助函数，减小体积
  ],
};

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,           // 生成 .d.ts 类型声明
    "sourceMap": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "jsx": "react-jsx"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

// package.json
{
  "scripts": {
    "build:types": "tsc --emitDeclarationOnly",  // 仅生成类型声明
    "build:js": "babel src --out-dir dist",       // Babel 转译
    "build": "npm run build:types && npm run build:js",
    "type-check": "tsc --noEmit"                  // 单独类型检查
  }
}

// vite.config.js
import checker from 'vite-plugin-checker';

export default defineConfig({
  plugins: [
    checker({ typescript: true }), // 在独立线程中运行 tsc --noEmit
  ],
});

// ----- 图片懒加载模块 -----
// heavy-image-gallery.js
export function initGallery(containerId) {
  console.log(`初始化图片画廊: ${containerId}`);
  // ... 大量的库代码
}

// ----- 按需加载 -----
document.getElementById('show-gallery').addEventListener('click', async () => {
  // import() 返回 Promise，Webpack/Vite 会自动分割代码
  const { initGallery } = await import('./heavy-image-gallery.js');
  initGallery('gallery-container');
});

// ----- App.jsx -----
import React, { Suspense, lazy } from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

// 懒加载组件
const HomePage = lazy(() => import('./pages/HomePage'));
const AboutPage = lazy(() => import('./pages/AboutPage'));
const DashboardPage = lazy(() => import('./pages/DashboardPage'));

// 加载指示器
function PageLoader() {
  return <div className="page-loader">Loading...</div>;
}

function App() {
  return (
    <BrowserRouter>
      <Suspense fallback={<PageLoader />}>
        <Routes>
          <Route path="/" element={<HomePage />} />
          <Route path="/about" element={<AboutPage />} />
          <Route path="/dashboard" element={<DashboardPage />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  );
}

export default App;

// 配合 React Router v6
import { lazy, Suspense } from 'react';
import { Routes, Route, Outlet } from 'react-router-dom';

const Users = lazy(() => import('./pages/Users'));
const UserDetail = lazy(() => import('./pages/UserDetail'));
const Settings = lazy(() => import('./pages/Settings'));

function SuspenseLayout() {
  return (
    <div>
      <header>导航栏</header>
      <Suspense fallback={<div>加载中...</div>}>
        <Outlet /> {/* 路由出口，懒加载子路由 */}
      </Suspense>
    </div>
  );
}

function AppRoutes() {
  return (
    <Routes>
      <Route element={<SuspenseLayout />}>
        <Route path="/users" element={<Users />} />
        <Route path="/users/:id" element={<UserDetail />} />
        <Route path="/settings" element={<Settings />} />
      </Route>
    </Routes>
  );
}

// 预获取（prefetch）— 浏览器空闲时加载，用于"将来可能用到"的资源
const AboutPage = import(/* webpackPrefetch: true */ './pages/AboutPage');

// 预加载（preload）— 当前页面需要立即用到的资源
const ChartLib = import(/* webpackPreload: true */ './lib/chart');

// 自定义 chunk 名称
const LazyComponent = import(/* webpackChunkName: "dashboard" */ './Dashboard');

// 在构建工具中也会自动注入对应的 <link>

// Vite 自动处理动态 import 的预加载，也可手动配置
// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            // 将第三方库自动分割
            if (id.includes('lodash')) return 'vendor_lodash';
            if (id.includes('react')) return 'vendor_react';
          }
        },
      },
    },
  },
});

<!-- 预加载关键 CSS -->
<link rel="preload" href="/styles/critical.css" as="style">

<!-- 预获取非关键 JS -->
<link rel="prefetch" href="/scripts/analytics.js">

<!-- 预加载字体 -->
<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>

# .env — 所有环境共享
APP_NAME=MyApp
VERSION=1.0.0

# .env.development — 开发环境
API_URL=http://localhost:3000/api
DEBUG=true

# .env.production — 生产环境
API_URL=https://api.example.com
DEBUG=false

# .env.local — 本地覆盖，不提交到 Git
# （已在 .gitignore 中忽略）
DB_PASSWORD=local_dev_only

// Vite 中环境变量必须以 VITE_ 开头才会暴露给客户端
console.log(import.meta.env.VITE_API_URL);
console.log(import.meta.env.MODE);    // development | production
console.log(import.meta.env.PROD);    // boolean
console.log(import.meta.env.DEV);     // boolean
console.log(import.meta.env.SSR);     // boolean

// vite.config.js
import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  // 加载当前模式的 env
  const env = loadEnv(mode, process.cwd(), '');

  return {
    define: {
      // 自定义全局常量
      __APP_VERSION__: JSON.stringify(env.APP_VERSION),
    },
    server: {
      proxy: {
        '/api': {
          target: env.API_URL,
        },
      },
    },
  };
});

// webpack.config.js
const webpack = require('webpack');

module.exports = (env, argv) => {
  const isDev = argv.mode === 'development';

  return {
    plugins: [
      new webpack.DefinePlugin({
        'process.env.NODE_ENV': JSON.stringify(argv.mode),
        'process.env.API_URL': JSON.stringify(
          isDev ? 'http://localhost:3000/api' : 'https://api.example.com'
        ),
        __DEV__: isDev,
      }),

      // 简写：自动读取 .env 中的变量
      new webpack.EnvironmentPlugin(['NODE_ENV', 'API_URL']),
    ],
  };
};

if (process.env.NODE_ENV === 'development') {
  console.log('开发模式');
}

const API_BASE = process.env.API_URL;

// package.json——多环境脚本
{
  "scripts": {
    "dev": "vite",                              // 开发
    "build:dev": "vite build --mode development", // 开发环境构建
    "build:staging": "vite build --mode staging", // 预发布构建
    "build:prod": "vite build --mode production", // 生产构建

    "analyze": "ANALYZE=true vite build",        // 分析构建产物
    "build:legacy": "vite build --mode legacy"   // 兼容旧浏览器
  }
}

// 创建不同环境的构建配置
// vite.config.js
export default defineConfig(({ mode }) => {
  const configs = {
    development: {
      sourcemap: true,
      minify: false,
    },
    staging: {
      sourcemap: true,
      minify: 'esbuild',
    },
    production: {
      sourcemap: false,
      minify: 'terser',
    },
    legacy: {
      target: ['ie >= 11'],
      plugins: [legacyPlugin()],
    },
  };

  return {
    ...configs[mode] || configs.development,
    // 公共配置
    plugins: [vue(), ...(configs[mode]?.plugins || [])],
  };
});

// .eslintrc.json
{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"  // 必须放在最后，覆盖 ESLint 的格式规则
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "plugins": ["react", "@typescript-eslint"],
  "rules": {
    "no-console": "warn",
    "react/react-in-jsx-scope": "off",
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
  }
}

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "tabWidth": 2,
  "printWidth": 100,
  "arrowParens": "always",
  "endOfLine": "lf"
}

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"]
}

# 安装
npx husky-init
npm install lint-staged --save-dev

// package.json
{
  "scripts": {
    "prepare": "husky install",
    "lint-staged": "lint-staged"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css,scss}": ["prettier --write"]
  }
}

# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

# .husky/commit-msg — 配合 commitlint 校验提交信息
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit $1

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2, 'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'perf'],
    ],
  },
};

# pnpm 使用内容寻址的文件系统，相同版本的包只存一份
# 所有项目共享，通过硬链接引用

# 安装依赖
pnpm install

# 添加依赖
pnpm add lodash

# 添加开发依赖
pnpm add -D typescript

# monorepo 工作区
pnpm -F @project/ui build

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],  // 依赖项目先构建
      "outputs": ["dist/**", ".next/**"],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}