引言：为什么需要PM2？

在Node.js生态中，进程管理是保障服务稳定性和高可用性的核心环节。随着业务复杂度的提升，开发者需要面对多进程调度、异常重启、日志收集、性能监控等挑战。传统的手动管理方式（如通过node app.js直接启动）在生产环境中显得力不从心。

PM2（Process Manager 2） 作为一款功能全面的进程管理工具，通过自动化和智能化的机制，为Node.js应用提供了从开发到部署的全生命周期支持。对于Vue3项目而言，虽然前端项目本身是静态资源，但在生产环境中同样需要稳定的服务进程来提供访问。

一、PM2核心功能详解

1.1 进程守护与自动重启

PM2最核心的功能之一是进程守护。当服务崩溃或意外退出时，PM2会自动重启应用，无需手动干预，保证服务7x24小时运行。这对于生产环境至关重要，避免了因单点故障导致的服务中断。

1.2 集群模式与负载均衡

PM2支持集群模式，可以自动利用多核CPU资源，将请求分发到多个进程，显著提升服务的并发处理能力。通过简单的配置，就能实现多实例负载均衡。

1.3 日志统一管理

PM2会自动记录服务的标准输出和错误日志，方便排查问题。你可以自定义日志路径，还可以安装pm2-logrotate插件实现日志自动切割，防止磁盘被日志文件撑满。

1.4 监控与性能统计

通过命令行或可视化工具，你可以实时查看服务的CPU、内存使用情况，掌握运行状态。pm2 monit命令提供了交互式监控界面，pm2 show可以查看单个服务的详细信息。

1.5 系统自启动

PM2支持设置开机自启动，服务器重启后服务自动恢复，无需重新手动启动。通过pm2 startup和pm2 save命令即可实现。

二、PM2安装与基本使用

2.1 安装PM2

# 全局安装PM2
npm install pm2 -g

# 验证安装
pm2 -v

2.2 常用命令速查表

命令	说明	示例
pm2 start [文件/配置]	启动服务	pm2 start app.js
pm2 stop [进程名/ID]	停止服务	pm2 stop my-app
pm2 restart [进程名/ID]	重启服务	pm2 restart my-app
pm2 delete [进程名/ID]	删除服务	pm2 delete my-app
pm2 list	查看所有进程状态	pm2 list
pm2 logs	查看日志	pm2 logs my-app
pm2 monit	实时监控	pm2 monit
pm2 save	保存当前进程列表	pm2 save
pm2 startup	设置开机自启	pm2 startup

三、Vue3项目中使用PM2的完整指南

3.1 构建Vue3项目

在使用PM2管理Vue3项目之前，首先需要构建项目生成静态文件：

# 进入Vue3项目目录
cd your-vue3-project

# 安装依赖（如果尚未安装）
npm install

# 构建项目
npm run build

构建完成后会生成dist文件夹，其中包含了所有静态资源文件。

3.2 创建PM2配置文件

PM2推荐使用ecosystem.config.js配置文件来管理应用，这种方式更易于维护和版本控制。在项目根目录创建该文件：

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'my-vue3-app',           // 应用名称
    script: 'serve',               // 使用serve启动静态服务器
    args: 'dist',                  // 指定dist目录
    exec_mode: 'fork',             // 执行模式：fork或cluster
    instances: 1,                  // 实例数量
    autorestart: true,             // 自动重启
    watch: false,                  // 生产环境关闭监听
    max_memory_restart: '1G',      // 内存超过1G自动重启
    env: {
      NODE_ENV: 'development',
      PM2_SERVE_PATH: './dist',    // 服务路径
      PM2_SERVE_PORT: 3000,        // 服务端口
      PM2_SERVE_SPA: 'true'        // 支持SPA路由
    },
    env_production: {
      NODE_ENV: 'production',
      PM2_SERVE_PATH: './dist',
      PM2_SERVE_PORT: 8080,
      PM2_SERVE_SPA: 'true'
    },
    error_file: './logs/error.log',   // 错误日志路径
    out_file: './logs/out.log',       // 输出日志路径
    log_date_format: 'YYYY-MM-DD HH:mm:ss'  // 日志时间格式
  }]
};

3.3 使用Express服务器方案（备选）

如果你需要更灵活的控制，可以使用Express创建自定义服务器：

// server.js
const express = require('express');
const path = require('path');
const app = express();

// 设置静态文件目录
app.use(express.static(path.join(__dirname, 'dist')));

// 支持SPA路由
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Vue3应用运行在端口 ${PORT}`);
});

然后在PM2配置中使用这个服务器文件：

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'vue3-express-app',
    script: './server.js',
    // ...其他配置
  }]
};

3.4 启动Vue3项目

# 使用配置文件启动
pm2 start ecosystem.config.js

# 或者指定生产环境
pm2 start ecosystem.config.js --env production

# 查看运行状态
pm2 status

# 查看实时日志
pm2 logs my-vue3-app

四、高级配置与最佳实践

4.1 集群模式配置

对于高并发场景，可以启用集群模式充分利用多核CPU：

module.exports = {
  apps: [{
    name: 'vue3-cluster-app',
    script: 'serve',
    args: 'dist',
    instances: 'max',      // 根据CPU核心数启动最大实例
    exec_mode: 'cluster',  // 集群模式
    // ...其他配置
  }]
};

4.2 环境变量管理

PM2支持多环境配置，便于开发、测试、生产环境的切换：

module.exports = {
  apps: [{
    name: 'vue3-app',
    script: 'serve',
    args: 'dist',
    env: {
      NODE_ENV: 'development',
      API_BASE_URL: 'http://localhost:3000/api',
      PORT: 3000
    },
    env_staging: {
      NODE_ENV: 'staging',
      API_BASE_URL: 'https://staging-api.example.com',
      PORT: 8080
    },
    env_production: {
      NODE_ENV: 'production',
      API_BASE_URL: 'https://api.example.com',
      PORT: 80
    }
  }]
};

启动时指定环境：

pm2 start ecosystem.config.js --env staging

4.3 日志管理与切割

生产环境中，日志管理至关重要：

# 安装日志切割插件
pm2 install pm2-logrotate

# 配置日志切割
pm2 set pm2-logrotate:max_size 50M    # 单个日志文件最大50MB
pm2 set pm2-logrotate:retain 10       # 保留10个日志文件
pm2 set pm2-logrotate:compress true   # 压缩旧日志
pm2 set pm2-logrotate:dateFormat 'YYYY-MM-DD_HH-mm-ss'  # 日志文件名格式

4.4 开机自启动配置

确保服务器重启后应用自动恢复：

# 生成启动脚本（根据系统提示执行相应命令）
pm2 startup

# 保存当前进程列表
pm2 save

# 重启后自动恢复
pm2 resurrect

4.5 监控与告警

PM2提供了丰富的监控功能：

# 实时监控界面
pm2 monit

# 查看应用详细信息
pm2 show vue3-app

# 生成系统报告
pm2 report

# 以JSON格式查看状态
pm2 jlist

五、Vue3项目部署完整流程

5.1 本地开发环境

# 1. 开发阶段使用Vue CLI
npm run serve

# 2. 构建生产版本
npm run build

# 3. 本地测试构建结果
npx serve dist

5.2 服务器部署流程

# 1. 上传代码到服务器
scp -r dist user@server:/path/to/project/

# 2. 在服务器上安装PM2（如果尚未安装）
npm install pm2 -g

# 3. 上传PM2配置文件
scp ecosystem.config.js user@server:/path/to/project/

# 4. 在服务器上启动应用
cd /path/to/project
pm2 start ecosystem.config.js --env production

# 5. 设置开机自启
pm2 startup
pm2 save

5.3 结合Nginx反向代理

对于生产环境，建议使用Nginx作为反向代理：

# /etc/nginx/sites-available/vue3-app
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;  # PM2运行的端口
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
    
    # 静态文件缓存
    location ~* .(jpg|jpeg|png|gif|ico|css|js)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

六、常见问题与解决方案

6.1 端口占用问题

如果端口已被占用，PM2会自动尝试其他端口，但最好明确指定：

env: {
  PORT: 3000,
  PM2_SERVE_PORT: 3000
}

6.2 内存泄漏监控

设置内存限制，超过阈值自动重启：

max_memory_restart: '512M'  // 内存超过512MB自动重启

6.3 文件变化监听（开发环境）

开发环境下可以启用文件监听：

watch: true,
ignore_watch: [
  'node_modules',
  'logs',
  '.git'
]

6.4 多应用管理

PM2可以同时管理多个应用：

module.exports = {
  apps: [
    {
      name: 'vue3-frontend',
      script: 'serve',
      args: 'dist',
      // ...前端配置
    },
    {
      name: 'node-backend',
      script: './server/api.js',
      // ...后端配置
    }
  ]
};

PM2作为Node.js生态中最流行的进程管理工具，为Vue3项目的生产部署提供了完整的解决方案。通过本文的介绍，你应该已经掌握了：

1. PM2的核心功能：进程守护、集群模式、日志管理、监控等
2. Vue3项目配置：如何通过ecosystem.config.js文件管理Vue3应用
3. 生产环境最佳实践：集群配置、日志切割、开机自启等
4. 完整部署流程：从本地开发到服务器部署的全过程

在实际项目中，建议始终使用配置文件而非命令行参数，这样配置更易于维护和版本控制。同时，结合Nginx等Web服务器，可以构建更加稳定和高效的生产环境。

PM2的学习曲线平缓，但功能强大，是每个Node.js和Vue开发者都应该掌握的工具。开始在你的Vue3项目中使用PM2，享受更加稳定和高效的部署体验吧！

提示：本文所有配置示例都经过实际测试，你可以根据项目需求进行调整。更多高级功能请参考PM2官方文档。

前言

Vue3 的 <script setup> 是官方推荐写法，代码更简洁、逻辑更聚合。本文带你真正用好组合式 API。

一、script setup 基本写法

<script setup>
// 直接写逻辑，无需 export default
import { ref, reactive, computed } from 'vue'

const msg = ref('Hello Vue3')
</script>

<template>
  <div>{{ msg }}</div>
</template>

二、响应式数据

• ref：基础类型（string/number/boolean）

• reactive：对象 / 数组

  const num = ref(0) const user = reactive({ name: '张三', age: 20 })

三、计算属性 computed

import { computed } from 'vue'

const doubleNum = computed(() => num.value * 2)

四、方法与事件

<button @click="add">+1</button>

<script setup>
const add = () => {
  num.value++
}
</script>

五、生命周期

import { onMounted, onUpdated, onUnmounted } from 'vue'

onMounted(() => {
  console.log('组件挂载')
})

六、父传子 props

// 子组件
<script setup>
import { defineProps } from 'vue'
const props = defineProps({
  title: String
})
</script>

七、子传父 emit

// 子组件
const emit = defineEmits(['change'])
const handleChange = () => {
  emit('change', '新数据')
}

八、获取 DOM：ref

<div ref="box"></div>

<script setup>
import { ref } from 'vue'
const box = ref(null)

onMounted(() => {
  console.log(box.value)
})
</script>

总结

<script setup> 优点：

• 代码更少
• 无需 return
• 更好的 TS 支持
• 逻辑更清晰

随着纯血鸿蒙 (HarmonyOS NEXT) 逐渐成为全球主流操作系统，将现有的前端业务延展至鸿蒙生态成为了许多开发团队的核心诉求。根据官方说明，Taro 从 v4.1.0 开始，已经正式支持打包纯血鸿蒙应用。如果你想了解详细的底层架构与特性，可以随时查阅官方文档。

在最新的 Taro 架构中，官方主推基于 C-API 的原生混合渲染模式（Harmony-CPP），它能够突破传统 JS 桥接的性能瓶颈，带来媲美原生的流畅体验。但在实际落地的过程中，从脚手架初始化到最终在 DevEco Studio 中点亮那颗“绿色运行按钮”，隐藏着不少工程化陷阱。本文将以真实的第一视角，带你一步步走完这个“从0到1”的实战全流程。

一、 初始化 Taro 脚手架：关键选项避坑

首先，我们需要全局安装 Taro CLI 并初始化项目。建议使用 yarn 或 pnpm 来管理跨端巨石应用：

npm install -g @tarojs/cli
taro init my-demo

在交互式问询界面中，有几个针对鸿蒙生态的必选项千万不能选错：

1. 框架：推荐选择 React。
2. 编译工具：必须选择 Vite。目前 Taro 明确规定，当前仅支持使用 Vite 编译鸿蒙应用。
3. 是否需要使用 TypeScript？ ：Yes。鸿蒙底层的 ArkTS 本质上是 TS 的超集，使用 TS 能让后续的原生混编更顺滑。
4. 是否需要编译为 ES5？ ：No。Vite 基于原生 ESM 构建，强行降级 ES5 会破坏编译性能且毫无必要。
5. 模板选择：选择默认模板 (default) ，保持代码结构的纯粹，最适合用来跑通基础链路。

二、 核心编译插件的安装与“隐形依赖”陷阱

初始化完成后，进入项目目录，我们需要安装鸿蒙 C-API 的专属编译插件：

yarn add @tarojs/plugin-platform-harmony-cpp

⚠️ 踩坑警告：

如果你仅仅安装了 harmony-cpp，在后续执行编译时，大概率会遇到如下报错：

Error: Cannot find module '@tarojs/plugin-platform-harmony-ets/dist'

原因与解法：Taro 的 cpp 插件在底层强依赖了 ets 插件内部的公共构建脚本与类型定义。因此，你必须手动补齐这个隐形依赖：

yarn add @tarojs/plugin-platform-harmony-ets

三、 在 DevEco Studio 中创建鸿蒙原生工程

在将 Taro 前端代码编译并注入之前，我们必须先通过华为开发者工具准备一个鸿蒙原生空壳工程。

1. 启动创建：打开 DevEco Studio。如果是首次打开，点击欢迎页面的 Create Project；如果已有项目打开，则从顶部菜单栏选择 File > New > Create Project。
2. 选择模板：在“Choose Your Ability Template”页面中，选择 Application，然后选中 Empty Ability 基础模板，点击 Next。
3. 配置工程：填写你的项目名称（Project name）和包名（Bundle name），并选择代码的保存目录（Save location）。请务必牢记这个保存目录的绝对路径，我们在下一步的 Taro 配置中马上会用到它 。
4. 选择版本：Compatible SDK 建议选择匹配你当前开发环境的较新版本（例如推荐的 API 12 及其对应版本）。
5. 完成创建：点击 Finish。IDE 会自动为你生成工程的基础代码结构与相关资源，等待项目初始化加载完成即可。

四、 配置鸿蒙本地工程路径

现在回到前端项目中，打开根目录下的 config/index.ts（或 index.js），注册鸿蒙插件并把你刚刚在上一步创建的底层空壳工程绝对路径配置进去：

const config = {
  //... 其他基础配置
  plugins: ['@tarojs/plugin-platform-harmony-cpp'],
  harmony: {
    compiler: 'vite', // 当前仅支持使用 Vite 编译鸿蒙应用
    // 注意：这里填写你刚才通过 DevEco Studio 创建的鸿蒙空壳工程的绝对路径
    projectPath: '/Users/你的用户名/DevEcoStudioProjects/MyApplication',
    hapName: 'entry',
  },
}

五、 编译并注入产物

配置无误后，在终端执行跨端编译指令：

taro build --type harmony_cpp

此时终端可能会在最后抛出一个警告：/bin/sh: ohpm: No such file or directory。

不用慌，这仅仅是因为你的电脑终端没有配置鸿蒙包管理器 ohpm 的全局环境变量。只要看到 ✓ built in xxx ms 就证明前端代码已经成功转换为 ArkTS 产物，并注入到了你指定的底层鸿蒙工程中。

六、 DevEco Studio 终极排错：点亮灰色的运行按钮

再次打开你的 DevEco Studio，回到刚才创建的空壳工程。此时你可能会发现右上角的绿色运行按钮变成了灰色不可用的状态，并且点击 Sync 还会报错。我们需要进行以下两步“清扫”工作来激活它：

1. 解决 ohpm install 同步问题

打开鸿蒙工程左侧目录树中的 oh-package.json5，点击编辑器右上角弹出的 Sync Now 按钮。这会接替终端，由 IDE 来完成所有依赖库的拉取。

2. 解决 EntryBackupAbility.ets Not Found 构建崩溃

当你尝试构建或同步时，底层的 Hvigor 构建引擎可能会抛出致命错误：

hvigor ERROR: 00304012 Not Found... Module-srcEntry./ets/entrybackupability/EntryBackupAbility.ets not found.

原因解析：DevEco Studio 创建新项目时，默认在 module.json5 中注册了用于备份与恢复数据的 entrybackupability 入口文件。但 Taro 注入产物时重写了目录结构，导致该文件丢失，从而引发构建配置的不匹配错误。

终极解法：

展开 entry -> src -> main -> module.json5，找到 "extensionAbilities" 节点，直接删除包含 backup 类型的整个对象配置。保存后，点击顶部菜单栏的 File -> Sync and Refresh Project。

3. 配置自动签名 (如果运行按钮依然灰色)

点击顶部 File -> Project Structure... -> Signing Configs，勾选 Automatically generate signature 并登录华为开发者账号，让 IDE 自动完成开发证书的签名配置。

七、 大功告成

完成以上所有步骤后，DevEco Studio 重新建立索引，右上角的绿色三角形运行按钮终于亮起！点击 Run，启动模拟器，你就会看到由 Taro 跨端编译出的 React 页面完美地运行在了纯血鸿蒙系统上！

结语

跨端框架适配纯血鸿蒙的过程，本质上是一场前端编译工具链与底层系统原生规则的“握手”。掌握了这套排错逻辑，你就可以毫无负担地在全场景跨端的广阔天地中尽情施展了。祝大家代码无 Bug，编译一遍过！

一、 回顾历史：虚拟 DOM 到底解决了什么痛点？

在 2013 年 React 带着虚拟 DOM (Virtual DOM) 出来之前，我们操作网页的方式是极其原始的。

1.1 被 jQuery 支配的年代

那时候我们要改一个列表，流程通常是这样的：

1. 拿到数据。
2. 找到对应的 DOM 节点。
3. 手动拼接字符串或者操作 appendChild。
4. 还要小心翼翼地处理事件解绑，否则内存就泄露了。

这种模式最大的问题不是“慢”，而是状态不可控。当页面逻辑复杂到一定程度，你根本不知道是哪一段脚本改了哪一个按钮。UI 和数据完全脱节，维护起来就像在代码里拆地雷。

1.2 虚拟 DOM 并不是为了追求绝对速度

这里必须纠正一个流传很久的误区：虚拟 DOM 比原生 DOM 快。

这个结论在底层逻辑上就是错的。

虚拟 DOM 本质上是一个普通的 JavaScript 对象（Plain Object）。当你修改数据时，框架会在内存里重新创建一个 JS 对象树，然后把新树和旧树对比（Diff），算出差异，最后再去调用原生 API（如 appendChild, remove, setAttribute）来更新网页。

你看，虚拟 DOM 多做了一步 JS 计算，它怎么可能比直接操作原生 DOM 更快？

1.3 虚拟 DOM 的真正功劳：性能兜底与开发范式

虚拟 DOM 解决的是两个核心问题：

• 研发效率：它让前端开发进入了“声明式”时代。你只需要告诉框架“我要的长相是什么样”，剩下的脏活累活（对比差异、局部更新）框架全包了。
• 防止低质量代码：新手开发者如果直接操作 DOM，很可能在循环里触发频繁的回流（Reflow），导致页面卡顿。虚拟 DOM 通过内部的缓冲合并机制，强行保证了即使你乱写，性能也不会掉出及格线。

二、 既然它这么好，为什么现在要“移除”它？

技术的发展总是伴随着成本。当我们的应用从简单的管理后台变成了像飞书、Figma 这样复杂的巨型 Web 应用时，虚拟 DOM 的副作用就开始显现了。

2.1 运行时计算的“天花板”

虚拟 DOM 的核心是 Diff 算法。无论算法怎么优化（比如 React 的 Fiber 架构），它始终避不开一个逻辑：当数据变化时，我要通过遍历树来“猜”哪里变了。

在一个有 5000 个节点的长列表里，即使你只是改了一个复选框的状态，框架依然要递归遍历这 5000 个虚拟节点，去确认其他 4999 个节点没变。这种计算开销是随着节点数量线性增长的。在主线程处理高频交互（如拖拽、输入）时，这种 Diff 耗时会导致明显的丢帧。

2.2 内存的沉重代价

虚拟 DOM 节点在内存里是很重的。除了节点类型、属性，还要存储各种 Hooks 状态、指向真实 DOM 的引用等。

对于内存受限的移动端设备，浏览器要同时维护一份真实 DOM 和一份（甚至两份）虚拟 DOM 镜像。这不仅占用了宝贵的内存空间，还会导致频繁的 GC (垃圾回收) 触发。每当 GC 扫描这些海量的小对象时，主线程就会瞬间停顿，造成页面微小的卡死。

2.3 SSR 场景下的冗余

现在的 Web 应用很看重首屏速度（LCP），通常会用服务器端渲染（SSR）。服务器生成了 HTML，发给浏览器显示。

但问题来了：为了让这个页面能交互，客户端的 JS 必须再跑一遍，在内存里构建一棵一模一样的虚拟 DOM 树，并跟真实 DOM 对接（这个过程叫 Hydration）。

既然 HTML 都已经渲染好了，为什么我还要在客户端重新算一遍 VDOM？ 这就是目前 VDOM 架构在性能优化上的一个死结。

三、 现代框架的进化：从“对比”转向“精准定位”

为了解决上述问题，Svelte、Solid.js 以及 Vue 3 的 Vapor Mode 开始尝试抛弃虚拟 DOM。它们的思路非常直白：既然运行时 Diff 太慢，那我就在编译阶段搞定。

3.1 编译器变得更聪明了

以前的编译器（如 Babel）只是把 JSX 翻译成 React.createElement。现在的编译器（如 Svelte 的编译器或 Vue 的模板分析器）在编译代码时，就能通过静态分析识别出：

• <div>姓名：{{ name }}</div> 这一行，只有 name 是动态的。
• 旁边的 <div>公司：字节跳动</div> 是静态的，一辈子都不会变。

3.2 细粒度更新：绕过 Diff

基于这种分析，编译器直接生成了原生 JS 代码，不再生成 VDOM。

当你修改 name 这个变量时，程序内部会直接执行：

textNode.data = newName;

没有 Diff 过程，没有树的遍历。 这就是所谓的“细粒度更新”。它就像是在代码里埋了一枚枚精准的雷管，哪里数据变了，就直接爆破哪里的 DOM 属性。

3.3 内存与运行时的精简

因为不需要在运行时存储虚拟树，也不需要内置复杂的 Diff 算法包，这些框架生成的产物体积更小，运行时的内存占用也极低。这在极致性能优化的场景下，简直是降维打击。

四、 对比：三种渲染方案的底层实现逻辑

为了让大家看得更透彻，我们用一段伪代码模拟三种方案的更新过程。

方案 A：原生命令式（jQuery）

JavaScript

// 数据变了
data.name = '张三';
// 开发者手动更新
$('#name-label').text('张三');

• 优点：最快。
• 缺点：当页面有 100 个地方要改，开发者会疯掉，代码没法维护。

方案 B：虚拟 DOM 模式（React/Vue2）

JavaScript

// 数据变了
state.name = '张三';
// 框架开始工作
let newVNode = render(state); // 重新生成整棵树
let patches = diff(oldVNode, newVNode); // 递归遍历对比差异
apply(realDOM, patches); // 把差异补丁打到真实 DOM 上

• 优点：开发爽，性能有保底。
• 缺点：数据变动越大，树越深，Diff 越累。

方案 C：编译时无虚拟 DOM 模式（Solid/Vapor）

JavaScript

// 编译阶段生成的代码（伪代码）
const name_updater = (val) => textNode1.data = val;

// 运行阶段数据变了
name.set('张三'); // 触发订阅函数
name_updater('张三'); // 直接定位更新，不经过对比

• 优点：速度接近原生操作，内存极省。
• 缺点：对编译器的依赖极强，目前动态性不如 VDOM。

五、 如何看待 VDOM 的未来？

虽然“去 VDOM 化”是目前的趋势，但作为资深前端，我们不能无脑跟风。VDOM 在未来相当长的一段时间内依然会有其独特的生态位。

5.1 跨平台场景的“万能胶水”

如果你的业务不只是 Web，还要出移动端 App（React Native）、小程序、甚至车载屏幕系统，虚拟 DOM 依然是最好的选择。

因为它本质上是一层抽象协议。它把 UI 变成了一个普通的 JS 对象。这个对象发给浏览器，浏览器能渲染成 HTML；发给 iOS，iOS 就能渲染成原生 View。这种解耦能力，目前“编译时直出真实 DOM”的方案还很难完美替代。

2.2 极致动态性的需求

有些业务需要从后台下发一份复杂的 JSON 布局，然后前端动态渲染。在这种完全依赖运行时的场景下，VDOM 的灵活性是非常强大的。

2.3 工业级平衡点：Vue 3 的策略

Vue 3 其实走了一条非常“中庸”且聪明的路。它保留了虚拟 DOM，但引入了 Patch Flags (静态标记) 。

它在编译模板时，会给动态节点打上标记（比如“这个节点只有 class 会变”）。在运行时 Diff 的时候，它会跳过所有静态节点，直接去跳到那个有标记的节点上操作。这本质上是带了“导航”的虚拟 DOM，在灵活性和性能之间找到了一个绝佳的平衡点。

六、 总结：我们该如何准备？

前端技术的演进不是为了“推翻”，而是为了“更高效地解决具体问题”。

• 对于极致性能追求的应用（如编辑器、大型看板、低功耗移动端）：你应该关注 Solid.js 或 Vue 的 Vapor Mode，去理解那种不需要 Diff 的精准更新思想。
• 对于通用型业务、多端复用的项目：成熟的 VDOM 框架（React, Vue 3）依然是目前工程化最稳妥、生态最丰富的选择。

我们没必要为了“虚拟 DOM 消失了”而感到焦虑。我们要关注的是渲染效率的本质：如何用更少的 JS 计算、更小的内存消耗，去实现更流畅的用户交互。

结论很简单：

过去，我们用 VDOM 来抹平 DOM 操作的复杂性；

现在，我们用更强大的编译器来抹平 VDOM 的额外开销。

前端渲染的尽头，始终是高效、精准、简洁的真实 DOM 操作。

转岗动机

先简单介绍一下我的背景：通信专业，秋招前自学前端，21 年 7 月校招进入某教育公司做前端开发。刚毕业就赶上行业寒冬，那会儿“双减”政策落地，教育行业整体受挫，我们组的业务也大受影响，年底我就有了准备跳槽的念头。

22 年 5 月，我加入字节，做了两年的前端开发。24 年 3 月，我们团队有一轮调整，当时前端人力有点冗余，后端则比较稀缺。当时的 +1 找我聊，问我愿不愿意试试转岗做后端。我没有纠结太久，原因很简单：换一个岗位，相当于多了一种视角，我会接触到完全不一样的一套知识体系，就算未来不继续做后端，了解后端体系对前端工作也是加分项。

所以当时的我抱着非常明确的“学习型心态”，接受了 +1 的提议。

转岗阵痛期

和 +1 沟通确认之后，我就开始正式接触团队的后端项目了。团队统一用 Go，所以技术栈没什么选择余地。

我的入门路线是：

第一步：搞定环境配置。安装 Go 环境、配置 IDE；快速过一遍 Go 基础语法；把项目跑起来，能在本地看到服务正常启动。得益于公司完善的文档体系，这一步没什么太大难度。

第二步：熟悉项目代码。从入口开始顺藤摸瓜，找逻辑简单的接口，看一看处理链路。

第三步：开始上手需求，在干中学。我写的第一个后端功能是数据导出，在那个需求里，我一边写一边学到了 Go 协程的用法、操作系统和内存管理以及 MongoDB 的数据存储和处理。

为了不让自己“只停留在能写”的状态，周末我会给自己留一点“作业”：研究项目里用到的框架是怎么组织代码的；熟悉各种数据库的常见用法，学习该怎么选型；内网搜罗各种“后端扫盲手册”，一点点补课。大概一个月之后，回头看自己写的第一个功能，我已经能发现问题并且知道怎么去优化了。那一刻还蛮有成就感的：我在进步。

但没高兴几天，真正的考验来了。

24 年 5 月，带我 landing 的后端同事转岗走了。在只学了个大概、刚能磕磕绊绊写需求的情况下，我被迫成了那个模块的“后端负责人”。这意味着我需要自己去拆解需求、写方案，自己接 oncall、处理用户问题，还要扛线上问题。

那段时间是我转岗后最痛苦的时期：我还不太会处理线上数据，怕操作失误没法回滚，遇到问题的第一反应甚至是“打不过就跑”。但人在压力下的成长往往是加速的，我比我想象的要更抗压更坚韧。周末打黑工 review 技术方案，处理用户问题到凌晨 —— 就这样硬着头皮扛了两三个月，直到组里招到了新的资深后端，我才松了口气。

那一阵过去之后，我拿到了那个季度的 spot bonus，+1 也非常肯定那段时间我的撑场表现。那一刻的心态变化很微妙：原本我以为自己不行的事情，其实也能撑下来；后端这条路，好像还可以再走远一点。

渐入佳境

24 年下半年（7月 - 12月），我持续做后端需求，同时有计划地补课：从数据存储、服务搭建，到中间件的使用，再到操作系统、并发控制、公司各种基建。

如果按季度拆解，大概是这样一个过程：Q3 能 cover 日常需求，线上有报警能第一时间看日志、查监控定位问题；遇到复杂问题不再“完全没头绪”。Q4 可以独立负责一些模块， 能从 0 到 1 设计技术方案；开始考虑性能和扩展性，而不仅仅是“先实现再说”。

回头看 24 年，我的收获远远超出了我的预期：我不仅完成了从前端到后端的角色转换，更重要的是，我开始有能力独立负责一个模块从设计到上线的全流程。到了 25 年，工作状态逐渐变得“得心应手”：独立完成项目，主动做性能优化，日常工作能从容应对。

回看这段转岗之路，也是我慢慢读懂并实践毛选智慧的过程。《实践论》教会我“干中学”，边干边学习，边学习边完善，循环往复，螺旋上升；《矛盾论》教会我“抓重点”，找准当前阶段最关键的问题，集中精力解决它，其他的也会随之理顺。

经验总结

如果只用一句话来总结我的体会，那就是：后端不用关注那么琐碎的交互和 UI，真好。当然这是半开玩笑，但也是真实的感受。

做前端时，习惯看交互反馈、动画细节、兼容性，各种像素级的“抠”。做后端之后，关注点转移到了业务逻辑、数据存储、服务稳定性。后端的世界有一种“更纯粹”的感觉。但这并不是说前端不重要 —— 前端承载了用户最直观的体验和感受，后端更像是系统的“地基和管道”，问题不显眼，但影响很大。

回头再看这段经历，我想说：转岗是一条没那么难的路，只要你会写代码，你就可以转岗。甚至在这个 Vibe coding 的时代，会不会写代码都已经不是最重要的事了。

重要的是，你是否愿意从头开始学习一套新体系、接受短期内变回“新人”的落差感、在一段时间里承受不确定性和压力。

对我自己来说，支撑我走过这段路的几个关键词是：

• 学习心态：把转岗当作一次进阶，不是“被动调岗”，而是“主动拓展边界”；

• 不畏难：遇到不懂的东西，不急着给自己贴“我不行”的标签，而是拆解问题一个个啃；

• 不给自己设限：有些事没做过，不代表做不了，试试又不会怎么样。

我的飞书签名一直是乔布斯的那句格言：过程即奖励。在这段经历里，我发现自己比想象中更能抗压，那些硬着头皮撑下来的日子，回过头看，恰恰是成长最快的时候。曾国藩说“吾生平长进，全在受挫受辱之时” —— 大概就是这个意思。

总而言之，如果你也有过类似的念头 —— 想换个方向，想看一看系统的另一面，或者单纯想跳出舒适区，那我真诚地献上一句来自“过来人”的鼓励：

你可以的。

只要你愿意试，愿意学，你肯定会有所收获。

以上，希望对你有点帮助：）

前言

Vue3 搭配 Vite 构建工具，开发速度飞起。这篇文章带你从 0 到 1 搭建一个标准 Vue3 工程化项目。

一、环境准备

确保你已安装：

• Node.js 16+
• npm / yarn / pnpm

二、使用 Vite 创建项目

npm create vite@latest

步骤：

1. 输入项目名
2. 选择 Vue
3. 选择 JavaScript 或 TypeScript

进入项目：

cd 项目名
npm install
npm run dev

打开浏览器即可看到 Vue3 欢迎页面。

三、项目结构说明

• main.js：入口文件
• App.vue：根组件
• components/：公共组件
• views/：页面组件
• router/：路由
• store/：状态管理
• assets/：静态资源

四、配置 Vue Router

安装：

npm install vue-router@4

新建 router/index.js：

import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'

const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home
  }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router

在 main.js 挂载：

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

createApp(App).use(router).mount('#app')

五、配置 Pinia 状态管理

安装：

npm install pinia

新建 store/index.js：

import { createPinia } from 'pinia'
const pinia = createPinia()
export default pinia

在 main.js 挂载：

import store from './store'
createApp(App).use(router).use(store).mount('#app')

总结

本文完成了：

• Vite + Vue3 项目创建
• Vue Router 4 路由配置
• Pinia 状态管理配置

下一篇我们讲 Vue3 组合式 API 最佳实践。

你在 NestJS 里看到的 @UseGuards()、@UsePipes()、app.useGlobalInterceptors() 这些，本质上都在做一件事：

• 把一段“横切逻辑”挂到请求处理链上
  比如：鉴权、参数校验、日志、统一返回体、统一异常格式……

这篇就用“人话”把三个问题讲清楚：

• NestJS 里可绑定的【元素】有哪些
• 全局绑定 vs 局部绑定：作用与区别
• 全局绑定的多种形式：各自原理/传参/差异/注意点，以及怎么选

本文所有结论都以 NestJS 官方文档为准（会在对应小节标注链接）。

目录

1. NestJS 里能“绑定”的【元素】有哪些？
2. 全局绑定 vs 局部绑定：作用与区别
3. 全局绑定的多种形式：到底差在哪？
4. 五类元素分别怎么绑、怎么传参、有哪些坑？
5. 选型：什么时候用哪种绑定方式？
6. 总结

---

1. NestJS 里能“绑定”的【元素】有哪些？

日常开发里，最常说的“绑定”，基本就这五类（也是官方文档重点讲的五条链路）：

• Middleware（中间件）：在路由处理前跑的一段函数/类，能拿到 req/res/next。
  参考：Middleware
• Guard（守卫）：决定“这次请求到底能不能进到 handler”。典型用来做鉴权/权限。
  参考：Guards
• Pipe（管道）：对入参做校验或转换（字符串转数字、DTO 校验等），发生在方法调用前。
  参考：Pipes
• Interceptor（拦截器）：更像 AOP，能在 handler 前后插逻辑、改返回值、做缓存、把异常映射成别的异常等。
  参考：Interceptors
• Exception Filter（异常过滤器）：专门兜异常，统一格式、打日志、屏蔽敏感信息等。
  参考：Exception filters

如果你要一个“背诵版”的链路顺序，官方明确写过的一句是：

• Guard 在所有 Middleware 之后执行，并且在任何 Interceptor 或 Pipe 之前执行
  参考：Guards - Hint

---

2. 全局绑定 vs 局部绑定：作用与区别（别背概念，直接按场景理解）

先把“范围”说清楚，后面选型才不容易绕晕。

• 局部绑定（Local / Scoped）：只影响“某个控制器 / 某个路由方法 / 某个参数”。
  典型写法：@UseGuards()、@UsePipes()、@UseInterceptors()、@UseFilters()，以及 Pipe 还能绑到参数上。
• 全局绑定（Global）：影响“整个应用里所有 controller + 所有 route handler”。
  典型写法：app.useGlobalXxx(...)、模块 providers 里用 APP_XXX、Middleware 的 app.use(...) / forRoutes('*')。

一句话区分：

• 局部绑定：像“给某个接口/模块单独加一条规则”
• 全局绑定：像“把规则写进公司制度，所有人默认都得遵守”

---

3. 全局绑定不止一种写法：到底差在哪？

这个是很多人纠结的核心：为什么全局还能写出两三种形式？我该用哪个？

3.1 main.ts 的 app.useGlobalXxx(new ...)：直给、简单，但 DI 有坑

以 Pipe 为例，官方给过最直观的全局写法：

// main.ts
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe());

参考：Pipes - Global scoped pipes

这种写法的本质是：你自己把实例 new 出来，挂到应用上。

• 优点：直观、配置集中、适合“纯配置型”的管道/拦截器（不需要注入任何 service）
• 最大的缺点：官方明确说了——在模块外注册的全局 Pipe/Guard/Interceptor/Filter 无法注入依赖
  参考：
  • Pipes - Global scoped pipes（DI 限制）
  • Guards - Binding guards（DI 限制）
  • Interceptors - Binding interceptors（DI 限制）
  • Exception filters - Binding filters（DI 限制）

还有个容易被忽略的“覆盖范围”问题：在混合应用（HTTP + WS/微服务）里，useGlobalPipes() / useGlobalGuards() 默认不一定覆盖网关/微服务。官方在 pipes/guards 里都有提醒。
参考：

• Pipes - Global scoped pipes（Hybrid app 提示）
• Guards - Binding guards（Hybrid app 提示）

3.2 模块里用 APP_PIPE / APP_GUARD / APP_INTERCEPTOR / APP_FILTER：更“框架化”，DI 友好

官方给的“解决 DI 问题”的标准姿势，就是把它注册成 provider：

// app.module.ts（示例：全局 Pipe）
import { APP_PIPE } from '@nestjs/core';

@Module({
  providers: [
    { provide: APP_PIPE, useClass: ValidationPipe },
  ],
})
export class AppModule {}

参考：Pipes - Global scoped pipes（APP_PIPE）

Guard / Interceptor / Filter 的写法完全一样，只是 token 变了：

• Guard：APP_GUARD 参考：Guards - Binding guards
• Interceptor：APP_INTERCEPTOR 参考：Interceptors - Binding interceptors
• Filter：APP_FILTER 参考：Exception filters - Binding filters

这种写法的本质是：交给 Nest DI 容器来创建实例。

• 优点：能注入依赖；更容易做可测试的设计；在复杂业务里更推荐
• 注意：官方也强调——不管你在哪个 module 里写，它都是“真的全局”，建议放在“该类定义所在的 module”
  参考同上各章的 Hint（都提到了“choose the module where X is defined”）

3.3 装饰器里传“类” vs 传“new 出来的实例”：你其实是在选“谁来创建对象”

官方在多个章节都写过：装饰器里你可以传类，也可以传实例。

以 Guard 为例：

@UseGuards(RolesGuard)       // 传类：Nest 来实例化，可 DI
@UseGuards(new RolesGuard()) // 传实例：你来实例化，一般就别指望 DI 了

参考：Guards - Binding guards

Pipe/Interceptor/Filter 也是同理（官方都写了“pass class enables dependency injection / pass in-place instance for customization”那套逻辑）。

简单粗暴的结论：

• 想要 DI：尽量传类（或用 APP_XXX）
• 想要按接口定制参数（比如某个 ParseIntPipe 想改 errorHttpStatusCode）：就传 new Xxx(options)

3.4 Middleware 的全局绑定更“特别”：app.use() 很香，但它根本进不了 DI

官方对 middleware 的说明更直白：

• app.use(logger) 能一次绑到所有路由，但无法访问 DI 容器
  参考：Middleware - Global middleware
• 如果你需要 DI，就别用 app.use()；改用 class middleware + .forRoutes('*')（它运行在 module 里，能注入）
  参考同上（官方也给了替代方案）

---

4. 逐个元素讲清楚：怎么绑、怎么传参、有哪些坑

下面每个元素我都给你：能绑在哪些层级 + 全局的几种写法 + 需要注意的点 + 伪代码

4.1 Middleware（中间件）

能绑在哪些层级

• 模块/路由级：consumer.apply(...).forRoutes(...)（最常用）
• 全局：app.use(...)（但不走 DI）

绑定伪代码

// 1) 模块内绑定（推荐：可 DI）
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('cats'); // 只绑 /cats

    consumer
      .apply(LoggerMiddleware)
      .forRoutes({ path: 'cats', method: RequestMethod.GET }); // 只绑 GET /cats

    consumer
      .apply(LoggerMiddleware)
      .exclude(
        { path: 'cats', method: RequestMethod.GET },
        'cats/{*splat}',
      )
      .forRoutes(CatsController); // 除了排除的，其他都绑
  }
}

// 2) 全局绑定（简单，但 DI 不可用）
const app = await NestFactory.create(AppModule);
app.use(logger); // logger 是 functional middleware

参考：Middleware - Applying middleware / Excluding routes / Global middleware

特别注意

• 不调用 next() 请求会挂住（官方原话就是“request will be left hanging”）
  参考：Middleware
• app.use() 的全局 middleware 拿不到 DI（要 DI 就用 .forRoutes('*') 那套）
  参考：Middleware - Global middleware
• Express 与 Fastify 的 middleware 签名不一样（官方有 warning）
  参考同上：Middleware - Warning

4.2 Guard（守卫）

能绑在哪些层级

• Controller 级：@UseGuards() 写在类上
• Method 级：@UseGuards() 写在方法上
• 全局：app.useGlobalGuards(...) 或 APP_GUARD

绑定伪代码

// 局部：controller 级
@Controller('cats')
@UseGuards(RolesGuard)
export class CatsController {}

// 局部：method 级
@Post()
@UseGuards(RolesGuard)
create() {}

// 全局：main.ts（不走 DI）
const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new RolesGuard());

// 全局：APP_GUARD（走 DI，推荐）
@Module({
  providers: [{ provide: APP_GUARD, useClass: RolesGuard }],
})
export class AppModule {}

参考：Guards - Binding guards

特别注意

• 执行顺序：Guard 在 middleware 之后，在 interceptor/pipe 之前
  参考：Guards - Hint
• 混合应用覆盖范围：useGlobalGuards() 在 hybrid app 默认不覆盖网关/微服务（官方 Notice）
  参考：Guards - Binding guards
• 全局 + DI：要 DI 就别在 main.ts 里 new，用 APP_GUARD
  参考同上（官方写得很明确）

4.3 Pipe（管道）

Pipe 这块“绑的层级”最多，也是最容易写出花的。

能绑在哪些层级

• 参数级：@Param('id', ParseIntPipe) / @Body(new ValidationPipe())
• 方法级：@UsePipes(...)
• Controller 级：@UsePipes(...) 写在类上
• 全局：useGlobalPipes() 或 APP_PIPE

绑定伪代码

// 参数级：把 id 转成 number，不行就直接 400
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {}

// 参数级：定制 options，就 new 一个实例
@Get(':id')
findOne(
  @Param('id', new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE }))
  id: number,
) {}

// 方法级：按接口传 schema（典型“每个接口一套校验规则”）
@Post()
@UsePipes(new ZodValidationPipe(createCatSchema))
create(@Body() dto: CreateCatDto) {}

// 全局：main.ts（不走 DI）
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe());

// 全局：APP_PIPE（走 DI，推荐）
@Module({
  providers: [{ provide: APP_PIPE, useClass: ValidationPipe }],
})
export class AppModule {}

参考：Pipes - Binding pipes / Global scoped pipes

特别注意

• Pipe 抛异常会进入异常层处理（官方叫 exceptions zone），抛了异常 handler 就不会执行
  参考：Pipes - Hint
• 混合应用覆盖范围：useGlobalPipes() 在 hybrid app 下默认不覆盖网关/微服务（官方 Notice）
  参考：Pipes - Global scoped pipes
• 全局 + DI：同样要用 APP_PIPE（官方直接点名）
  参考同上

4.4 Interceptor（拦截器）

能绑在哪些层级

• Controller / Method 级：@UseInterceptors(...)
• 全局：useGlobalInterceptors() 或 APP_INTERCEPTOR

绑定伪代码

// 局部：controller 级
@UseInterceptors(LoggingInterceptor)
export class CatsController {}

// 全局：main.ts（不走 DI）
const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new LoggingInterceptor());

// 全局：APP_INTERCEPTOR（走 DI，推荐）
@Module({
  providers: [{ provide: APP_INTERCEPTOR, useClass: LoggingInterceptor }],
})
export class AppModule {}

参考：Interceptors - Binding interceptors

特别注意

• 拦截器里如果你不调用 next.handle()，handler 根本不会执行（官方写得很直）
  参考：Interceptors - Call handler
• 响应映射有个坑：官方警告过，直接用 @Res() 这种“库特定响应策略”会让 response mapping 不工作
  参考：Interceptors - Response mapping（Warning）
• 全局 + DI：还是那句，用 APP_INTERCEPTOR
  参考：Interceptors - Binding interceptors

4.5 Exception Filter（异常过滤器）

能绑在哪些层级

• Method / Controller 级：@UseFilters(...)
• 全局：useGlobalFilters() 或 APP_FILTER

绑定伪代码

// 局部：method 级
@Post()
@UseFilters(HttpExceptionFilter) // 推荐传类，让 Nest 复用实例
create() {}

// 全局：main.ts（不走 DI）
const app = await NestFactory.create(AppModule);
app.useGlobalFilters(new HttpExceptionFilter());

// 全局：APP_FILTER（走 DI，推荐）
@Module({
  providers: [{ provide: APP_FILTER, useClass: HttpExceptionFilter }],
})
export class AppModule {}

参考：Exception filters - Binding filters

特别注意

• 官方建议“尽量传类而不是传实例”，原因是可复用、内存更友好
  参考：Exception filters - Hint（Prefer applying filters by using classes）
• useGlobalFilters() 不会给 gateways / hybrid apps 设置过滤器（官方 Warning）
  参考同上：Exception filters - Warning
• 如果你写了一个 @Catch() 什么都不填的“兜底过滤器”，并且还写了某些“只抓特定异常”的过滤器，官方提醒：兜底的要先声明
  参考：Exception filters - Catch everything（Warning）

---

5. 到底怎么选？给你一套“能直接落地”的决策规则

你可以按这几个问题来选，基本不踩坑。

5.1 这段逻辑是不是“所有接口都必须有”？

• 是（比如统一校验/统一返回体/统一异常格式/全局鉴权）：倾向全局
• 不是（只对某几个接口/某个模块生效）：局部绑定，别污染全局

5.2 这段逻辑要不要注入 Service / Config / DB / Cache？

• 要 DI：
  • Guard/Pipe/Interceptor/Filter：优先用 APP_GUARD / APP_PIPE / APP_INTERCEPTOR / APP_FILTER
  • Middleware：优先用 class middleware + consumer.apply(...).forRoutes('*')
• 不要 DI：
  • 你就可以用 main.ts 的 useGlobalXxx(new ...) 或 app.use(...)，写起来最快

（这些 DI 限制和替代方案，官方都写在对应章节里了：
Pipes、Guards、Interceptors、Exception filters、Middleware）

5.3 你需要“每个接口参数不一样”吗？

• 需要（比如某个 Pipe 要带不同 options、或者每个接口校验 schema 不一样）：局部 new Xxx(options) 更合适
• 不需要（全站统一同一套配置）：全局注册一次，别每个方法都写一遍

5.4 你项目是不是 hybrid（HTTP + WS/微服务）？

如果是，别默认以为 useGlobalXxx() 就全覆盖。官方在 pipes/guards/filters 里都写了“hybrid app”的注意点，建议你在项目里明确验证一下覆盖范围：

• Pipes - Global scoped pipes
• Guards - Binding guards
• Exception filters - Binding filters

---

6. 总结

• 能绑定的核心元素就 5 个：Middleware、Guard、Pipe、Interceptor、Exception Filter。
• 局部绑定解决“精准控制”：只对某个 controller / method / param 生效，最不容易“误伤”别的模块。
• 全局绑定解决“统一规则”：所有接口默认生效，但你要对“DI 能不能用、hybrid 覆盖范围”保持敏感。
• 全局绑定最重要的分水岭是 DI：
  • main.ts 的 useGlobalXxx(new ...)：快，但基本不走 DI
  • module 里的 APP_XXX：更工程化，DI 友好，复杂项目更推荐
  • middleware 的 app.use()：最简单，但拿不到 DI；要 DI 就 .forRoutes('*')
• 装饰器传“类”还是“实例”：你其实是在决定“让 Nest 创建对象（可 DI、可复用）”还是“自己 new（方便定制参数）”。

Docker 从入门到部署实战

---

1. Docker基础

1.1 Docker 基础概念

1.1.1 容器化

容器化是一种轻量级的虚拟化技术，将应用程序及其所有依赖项打包到一个**标准化的单元（容器）**中，确保应用在任何环境中都能一致运行。

核心思想："Build once, Run anywhere"

graph LR
    A[开发者编写代码] --> B[打包为容器镜像]
    B --> C[开发环境运行]
    B --> D[测试环境运行]
    B --> E[生产环境运行]
    style B fill:#0db7ed,color:#fff

1.1.2 容器 vs 虚拟机

graph TB
    subgraph 虚拟机架构
        direction TB
        H1[物理硬件]
        HV[Hypervisor 虚拟机管理程序]
        subgraph VM1[虚拟机1]
            G1[Guest OS]
            B1[Bins/Libs]
            A1[App A]
        end
        subgraph VM2[虚拟机2]
            G2[Guest OS]
            B2[Bins/Libs]
            A2[App B]
        end
        H1 --> HV
        HV --> VM1
        HV --> VM2
    end

    subgraph 容器架构
        direction TB
        H2[物理硬件]
        OS[Host OS 宿主操作系统]
        DE[Docker Engine]
        subgraph C1[容器1]
            CB1[Bins/Libs]
            CA1[App A]
        end
        subgraph C2[容器2]
            CB2[Bins/Libs]
            CA2[App B]
        end
        H2 --> OS
        OS --> DE
        DE --> C1
        DE --> C2
    end

特性	容器	虚拟机
启动速度	秒级	分钟级
体积	MB 级	GB 级
性能	接近原生	有损耗
隔离性	进程级隔离	完全隔离
操作系统	共享宿主内核	独立 Guest OS
资源占用	极少	较多
单机数量	数百个	通常几十个

1.1.3 Docker 架构

Docker 采用 C/S（客户端-服务端）架构。

graph LR
    subgraph Client[Docker Client 客户端]
        CMD["docker build<br>docker pull<br>docker run<br>docker ps<br>..."]
    end

    subgraph Host[Docker Host 宿主机]
        DAEMON[Docker Daemon<br>dockerd]
        subgraph Images[镜像]
            IMG1[nginx:latest]
            IMG2[node:18]
            IMG3[mysql:8.0]
        end
        subgraph Containers[容器]
            CON1[web-server]
            CON2[api-app]
        end
        DAEMON --> Images
        DAEMON --> Containers
    end

    subgraph Registry[Registry 镜像仓库]
        DH[Docker Hub]
        PR[私有仓库]
    end

    Client -->|REST API| DAEMON
    DAEMON -->|pull / push| Registry

三大核心组件：

组件	说明
Docker Client	用户与 Docker 交互的命令行工具，发送命令给 Daemon
Docker Daemon	后台守护进程，负责构建、运行和管理容器
Docker Registry	存储和分发镜像的仓库服务

1.1.4 核心概念

1.1.4.1 镜像（Image）

镜像是一个只读模板，包含运行应用所需的一切：代码、运行时、库、环境变量、配置文件。

graph TB
    subgraph 镜像分层结构
        direction TB
        L1[Layer 4: 应用代码 COPY . /app]
        L2[Layer 3: 安装依赖 RUN npm install]
        L3[Layer 2: 设置工作目录 WORKDIR /app]
        L4[Layer 1: 基础镜像 FROM node:18-alpine]
        L1 --> L2 --> L3 --> L4
    end
    style L1 fill:#0db7ed,color:#fff
    style L2 fill:#1a9bd7,color:#fff
    style L3 fill:#2980b9,color:#fff
    style L4 fill:#3867a8,color:#fff

关键特性：

• 分层存储：每一层都是只读的，层与层之间可复用，节省磁盘空间
• 写时复制（Copy-on-Write）：容器运行时在最上层添加可写层
• 通过 Dockerfile 构建：使用声明式语法定义镜像内容

常用命令：

docker images                  # 列出本地镜像
docker pull nginx:latest       # 从仓库拉取镜像
docker rmi nginx:latest        # 删除镜像
docker build -t myapp:1.0 .    # 构建镜像
docker tag myapp:1.0 myapp:v1  # 为镜像创建新的标签引用，不会复制镜像，两个标签指向同一镜像 ID
docker image prune             # 删除所有无标签（<none>）的悬空镜像，加 -a 可删除所有未被容器引用的镜像

1.1.4.2 容器（Container）

容器是镜像的运行实例，拥有自己的文件系统、网络、进程空间。

stateDiagram-v2
    [*] --> Created: docker create
    Created --> Running: docker start
    Running --> Paused: docker pause
    Paused --> Running: docker unpause
    Running --> Stopped: docker stop
    Stopped --> Running: docker start
    Running --> Stopped: docker kill
    Stopped --> Deleted: docker rm
    Deleted --> [*]

常用命令：

docker run -d --name web -p 80:80 nginx    # 基于 nginx 镜像创建名为 web 的容器，后台运行并将宿主机 80 端口映射到容器 80 端口
docker ps                                   # 查看运行中的容器
docker ps -a                                # 查看所有容器（含停止的）
docker stop web                             # 停止容器
docker start web                            # 启动容器
docker restart web                          # 重启容器
docker rm web                               # 删除容器
docker exec -it web bash                    # 进入容器交互终端
docker logs -f web                          # 查看容器日志（持续输出）

docker run 常用参数：

参数	说明	示例
-d	后台运行	docker run -d nginx
-p	端口映射	-p 8080:80（宿主机:容器）
--name	容器名称	--name my-nginx
-v	挂载数据卷：将宿主机目录映射到容器内目录，实现数据持久化和文件共享（容器删除后数据不丢失）	-v /host/path:/container/path
-e	设置容器内的环境变量，容器内的应用可通过 process.env（Node）或 os.environ（Python）等方式读取；常用于传递数据库密码、端口号等配置，无需修改镜像即可改变应用行为	-e MYSQL_ROOT_PASSWORD=123
--rm	容器停止后自动删除该容器（不会删除镜像），常用于临时测试场景	docker run --rm nginx
--network	将容器加入指定的 Docker 网络，同一网络内的容器可通过容器名互相访问（如 web 容器访问 db 容器）	--network my-net
-it	-i 保持标准输入打开 + -t 分配伪终端，组合使用可进入容器内的交互式命令行（类似 SSH 进入服务器）	docker run -it ubuntu bash

1.1.4.3 仓库（Registry）

Registry 是集中存储和分发镜像的服务。

graph TB
    subgraph 公共仓库
        DH[Docker Hub<br>hub.docker.com]
        GH[GitHub Container Registry<br>ghcr.io]
        AL[阿里云镜像仓库<br>registry.cn-hangzhou.aliyuncs.com]
    end
    subgraph 私有仓库
        HR[Harbor]
        NX[Nexus]
        RE[Docker Registry]
    end

    DEV[开发者] -->|docker push| DH
    DEV -->|docker pull| DH
    DEV -->|docker push| HR
    DEV -->|docker pull| HR

镜像命名规范：

[仓库地址/]命名空间/镜像名:标签

示例：
nginx:latest                                       # 官方镜像，默认 Docker Hub
library/nginx:1.25                                 # 完整官方路径
registry.cn-hangzhou.aliyuncs.com/myns/myapp:v1.0  # 阿里云私有仓库

常用命令：

docker login                        # 登录 Docker Hub
docker login registry.example.com   # 登录私有仓库
docker push myrepo/myapp:1.0       # 推送镜像到仓库
docker pull myrepo/myapp:1.0       # 从仓库拉取镜像
docker search nginx                 # 搜索 Docker Hub 上的镜像

---

1.2 环境搭建（Windows + WSL Ubuntu）

1.2.1 整体架构

graph TB
    subgraph Windows[Windows 宿主机]
        PS[PowerShell / Terminal]
    end
    subgraph WSL2[WSL 2 - Ubuntu]
        subgraph DockerEngine[Docker Engine]
            CLI[Docker Client<br>docker CLI 命令行工具]
            DAEMON[Docker Daemon<br>dockerd 后台守护进程]
            RT[containerd + runc<br>容器运行时]
            CLI -->|REST API| DAEMON
            DAEMON --> RT
        end
        subgraph Containers[运行中的容器]
            C1[nginx]
            C2[mysql]
            C3[node-app]
        end
        RT --> Containers
    end
    PS -->|wsl 命令进入| WSL2

不安装 Docker Desktop，直接在 WSL 2 Ubuntu 中安装 Docker Engine，轻量且免费。

Docker Engine 包含的组件：

组件	包名	说明
Docker Client	docker-ce-cli	命令行工具，用户输入 docker 命令时调用的就是它
Docker Daemon	docker-ce	后台守护进程 dockerd，负责管理镜像、容器、网络、存储卷
containerd	containerd.io	容器运行时，负责容器的生命周期管理（创建、启动、停止）
BuildKit	docker-buildx-plugin	新一代镜像构建引擎
Compose	docker-compose-plugin	多容器编排工具，通过 docker compose 命令使用

1.2.2 Docker 安装

步骤一：启用 WSL 2

以管理员身份打开 PowerShell：

# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑后，设置 WSL 默认版本为 2
wsl --set-default-version 2

# 安装 Ubuntu（如果尚未安装）
wsl --install -d Ubuntu

# 查看已安装的发行版及 WSL 版本（确认 VERSION 为 2）
wsl -l -v

步骤二：在 WSL Ubuntu 中安装 Docker Engine

# 进入 WSL Ubuntu
wsl -d Ubuntu

# 卸载旧版本（如有）
sudo apt-get remove docker docker-engine docker.io containerd runc

# 更新本地包索引（从软件源同步最新的可用包列表）
sudo apt-get update

# 安装添加 Docker 仓库源所需的依赖工具，-y 表示自动确认安装
sudo apt-get install -y \
    ca-certificates \  # CA 根证书，用于 HTTPS 请求时验证服务器证书的合法性
    curl \             # HTTP 命令行工具，用于下载 Docker 的 GPG 密钥
    gnupg \            # GPG 加密工具，用于验证下载的软件包签名是否可信
    lsb-release        # 提供 Linux 发行版信息（如版本代号），用于拼接正确的仓库地址

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加 Docker 仓库源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 将当前用户加入 docker 组（免 sudo 执行 docker 命令）
sudo usermod -aG docker $USER

# 重新登录 WSL 使用户组权限生效
exit
wsl -d Ubuntu

步骤三：设置 Docker 服务自动启动

WSL 2 默认不使用 systemd，需要手动启动 Docker 服务或开启 systemd。

systemd 是 Linux 的系统和服务管理器，负责在系统启动时自动拉起各种后台服务（如 Docker Daemon、网络、日志等）。类似 Windows 的"服务管理器"（services.msc），开启后 Docker 服务会随系统启动自动运行，无需每次手动执行 sudo service docker start。

方式一：开启 WSL systemd 支持（推荐）

# 编辑 WSL 配置文件
sudo tee /etc/wsl.conf <<-'EOF'
[boot]
systemd=true
EOF

然后在 PowerShell 中重启 WSL：

wsl --shutdown
wsl -d Ubuntu

重启后 Docker 会随 systemd 自动启动。

方式二：每次手动启动

# 启动 Docker 服务
sudo service docker start

1.2.3 镜像加速配置

国内访问 Docker Hub 较慢，需要配置镜像加速器。

在 WSL Ubuntu 中配置：

# 创建或编辑 daemon.json
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.rainbond.cc"
  ]
}
EOF

# 重启 Docker 服务
sudo systemctl daemon-reload
sudo systemctl restart docker

提示：镜像加速地址可能会变化失效，可关注 docker-practice/docker-registry-cn-mirror-test 获取最新可用地址。

1.2.4 验证安装

基本验证

# 查看 Docker 版本
docker --version
# 输出示例：Docker version 27.x.x, build xxxxxxx

# 查看详细版本信息（Client + Server）
docker version

# 查看 Docker 系统信息
docker info

运行测试容器

# 运行 hello-world 测试镜像
docker run hello-world

看到以下输出说明安装成功：

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

验证镜像加速是否生效

# 查看 docker info 中的 Registry Mirrors 字段
docker info | grep -A 5 "Registry Mirrors"

# 输出示例：
#  Registry Mirrors:
#   https://docker.1ms.run/
#   https://docker.xuanyuan.me/
#   https://docker.rainbond.cc/

运行一个实际容器验证

# 运行 nginx 并映射端口
docker run -d --name test-nginx -p 8080:80 nginx

# 访问测试
curl http://localhost:8080
# 应返回 nginx 欢迎页 HTML

# 查看运行中的容器
docker ps

# 清理测试容器
docker stop test-nginx && docker rm test-nginx

---

1.3 基础命令

1.3.1 镜像管理

命令	说明	示例
docker search	搜索镜像	docker search nginx
docker pull	拉取镜像（默认 latest）	docker pull nginx:1.25-alpine
docker images	列出本地镜像	docker images -q（仅显示 ID）
docker inspect	查看镜像详细信息	docker inspect nginx:latest
docker history	查看镜像构建历史（各层信息）	docker history nginx:latest
docker tag	给镜像打标签	docker tag nginx:latest myrepo/nginx:v1
docker push	推送镜像到仓库	docker push myrepo/nginx:v1
docker save	导出镜像为 tar 文件	docker save -o nginx.tar nginx:latest
docker load	从 tar 文件加载镜像	docker load -i nginx.tar
docker rmi	删除镜像	docker rmi nginx:latest
docker image prune	清理悬空镜像（无标签 <none>）	docker image prune -a（清理所有未引用镜像）

1.3.2 容器管理

命令	说明	示例
docker run	创建并启动容器	docker run -d --name web -p 8080:80 nginx
docker create	仅创建容器（不启动）	docker create --name web nginx
docker ps	查看容器	docker ps -a（含停止的） docker ps -q（仅 ID）
docker start	启动容器	docker start web
docker stop	停止容器	docker stop web
docker restart	重启容器	docker restart web
docker kill	强制停止容器	docker kill web
docker pause	暂停容器	docker pause web
docker unpause	恢复容器	docker unpause web
docker inspect	查看容器详细信息	docker inspect web
docker logs	查看容器日志	docker logs -f --tail 100 web
docker top	查看容器内进程	docker top web
docker stats	查看容器资源使用	docker stats web
docker cp	容器与宿主机复制文件	docker cp web:/etc/nginx/nginx.conf ./（容器→宿主机） docker cp ./index.html web:/usr/share/nginx/html/（宿主机→容器）
docker rm	删除容器	docker rm -f web（强制删除）
docker container prune	清理所有已停止的容器	docker container prune

1.3.3 容器交互

命令	说明	示例
docker exec -it	进入运行中的容器（推荐）	docker exec -it web bash docker exec -it web sh（alpine 等轻量镜像）
docker exec -it -u root	以 root 身份进入容器	docker exec -it -u root web bash
docker exec	在容器中执行单条命令	docker exec web cat /etc/nginx/nginx.conf
docker exec -e	设置环境变量并执行命令	docker exec -e MY_VAR=hello web env
docker run -it --rm	交互模式启动临时容器（退出自动删除）	docker run -it --rm ubuntu bash
docker attach	连接容器主进程	docker attach web（Ctrl+P Ctrl+Q 分离）
docker logs -f	持续查看容器日志	docker logs -f --tail 50 web

exec vs attach： exec 在容器内启动新进程，退出不影响容器运行；attach 连接到容器主进程（PID 1），退出可能导致容器停止。推荐使用 exec。

1.3.4 资源限制

Docker 默认不对容器做资源限制，容器可消耗宿主机全部可用资源。在生产环境中，必须通过以下参数限制资源，防止单个容器耗尽资源导致宿主机或其他容器不可用。

参数	说明	示例
--memory / -m	容器可使用的最大物理内存。超出限制时容器内进程会被 OOM Killer 杀掉。支持单位：b、k、m、g	docker run -d --memory 512m nginx
--memory-swap	内存 + swap 总上限（须 ≥ --memory）。swap 是磁盘上的虚拟内存空间，物理内存不足时系统将部分不活跃数据暂存到磁盘，速度远慢于内存但可防止进程被 OOM 杀掉。设为与 --memory 相同值则禁用 swap	docker run -d --memory 512m --memory-swap 1g nginx（物理内存 512m + swap 512m）
--cpus	容器最多可使用的 CPU 核数。1.5 表示最多使用 1.5 个核心的计算能力	docker run -d --cpus 1.5 nginx
--cpu-shares	CPU 时间片的相对权重（默认 1024）。仅在 CPU 资源争抢时生效：权重 512 的容器获得的 CPU 时间是 1024 的一半。CPU 空闲时不受此限制	docker run -d --cpu-shares 512 nginx
--pids-limit	容器内最大进程数，防止 fork 炸弹（恶意或意外无限创建进程）耗尽系统进程表	docker run -d --pids-limit 100 nginx

组合使用示例：

docker run -d --name web \
    --memory 512m \
    --cpus 1.5 \
    --pids-limit 100 \
    -p 8080:80 \
    nginx

运行时更新资源限制（无需重启容器）：

docker update --memory 1g --cpus 2 web

---

2. Docker 镜像与容器深入

2.1 镜像原理

2.1.1 镜像分层结构

Docker 镜像由多个**只读层（Layer）**叠加而成，每层对应 Dockerfile 中的一条指令。层之间共享复用，极大节省磁盘空间和传输时间。

graph TB
    subgraph 镜像分层示意
        direction TB
        W[可写层 Container Layer]
        L4[Layer 4: CMD / EXPOSE]
        L3[Layer 3: COPY 应用代码]
        L2[Layer 2: RUN npm install]
        L1[Layer 1: FROM node:18-alpine]
        W -->|写时复制 CoW| L4
        L4 --> L3 --> L2 --> L1
    end
    style W fill:#e74c3c,color:#fff
    style L4 fill:#0db7ed,color:#fff
    style L3 fill:#1a9bd7,color:#fff
    style L2 fill:#2980b9,color:#fff
    style L1 fill:#3867a8,color:#fff

核心机制：

概念	说明
联合文件系统（UnionFS）	将多个只读层合并为一个统一的文件系统视图，容器看到的是完整的目录结构
写时复制（Copy-on-Write）	容器运行时在最上层添加可写层；修改文件时先从只读层复制到可写层再修改，不影响原始镜像
层缓存	构建镜像时，未变化的层直接使用缓存，只重建变化的层及其之后的层
内容寻址	每层通过 SHA256 哈希标识，相同内容的层在不同镜像间共享

# 查看镜像分层信息
docker history nginx:latest

# 查看镜像详细元数据（含每层 diff ID）
docker inspect nginx:latest

# 查看镜像实际磁盘占用（含共享层）
docker system df -v

2.1.2 镜像标签

标签（Tag）用于标识镜像的不同版本，同一镜像可以有多个标签。

镜像全名格式：[仓库地址/]命名空间/镜像名:标签

示例：
nginx:latest          # latest 是默认标签，指向最新版本
nginx:1.25-alpine     # 指定版本 + 变体
node:18-slim          # slim 变体，精简版
python:3.12-bookworm  # 基于 Debian Bookworm

常见标签约定：

标签格式	说明
latest	最新版本（不建议生产使用，内容可能随时变化）
1.25 / 18	主版本号，会随小版本更新
1.25.3	精确版本号（生产推荐）
alpine	基于 Alpine Linux，体积极小（约 5MB）
slim	精简版 Debian，移除了不常用的包
bookworm / bullseye	基于特定 Debian 版本代号

# 给镜像打标签
docker tag nginx:latest myrepo/nginx:v1.0
docker tag nginx:latest myrepo/nginx:production

# 查看本地所有标签
docker images nginx

# 删除特定标签（不删除镜像本身，除非是最后一个标签）
docker rmi myrepo/nginx:v1.0

2.1.3 镜像仓库

graph LR
    DEV[开发者] -->|docker build| LOCAL[本地镜像]
    LOCAL -->|docker tag + push| REG[远程仓库]
    REG -->|docker pull| SERVER[服务器]

    subgraph 仓库类型
        PUB[公共仓库<br>Docker Hub / 阿里云]
        PRI[私有仓库<br>Harbor / Registry]
    end

常用公共仓库：

仓库	地址	说明
Docker Hub	hub.docker.com	全球最大，官方镜像仓库
阿里云 ACR	cr.console.aliyun.com	国内访问快，免费个人版
GitHub GHCR	ghcr.io	与 GitHub 深度集成
腾讯云 TCR	cloud.tencent.com/product/tcr	腾讯云容器镜像服务

# 登录 Docker Hub
docker login

# 登录私有仓库
docker login registry.cn-hangzhou.aliyuncs.com

# 推送镜像（需先 tag 为仓库地址前缀）
docker tag myapp:v1 registry.cn-hangzhou.aliyuncs.com/mynamespace/myapp:v1
docker push registry.cn-hangzhou.aliyuncs.com/mynamespace/myapp:v1

# 从私有仓库拉取
docker pull registry.cn-hangzhou.aliyuncs.com/mynamespace/myapp:v1

# 登出
docker logout registry.cn-hangzhou.aliyuncs.com

2.1.4 镜像导入导出

在无法访问外网或需要离线部署时，可通过导入导出在不同机器间传输镜像。

# 导出镜像为 tar 文件
docker save -o nginx.tar nginx:latest

# 导出多个镜像到一个文件
docker save -o images.tar nginx:latest mysql:8.0 redis:7

# 导入镜像
docker load -i nginx.tar

# 从容器导出文件系统（不含镜像元数据，仅文件系统快照）
docker export -o container-fs.tar my-container

# 从文件系统快照导入为新镜像
docker import container-fs.tar myimage:snapshot

save/load vs export/import： save/load 操作的是镜像，保留完整的分层和元数据，用于镜像迁移；export/import 操作的是容器文件系统，会丢失分层和历史记录，合并为单层镜像。

2.2 容器生命周期

2.2.1 容器状态

stateDiagram-v2
    [*] --> Created: docker create / docker run
    Created --> Running: docker start
    Running --> Paused: docker pause
    Paused --> Running: docker unpause
    Running --> Stopped: docker stop（优雅停止，先 SIGTERM 后 SIGKILL）
    Running --> Stopped: docker kill（强制停止，直接 SIGKILL）
    Stopped --> Running: docker start
    Stopped --> Deleted: docker rm
    Running --> Deleted: docker rm -f
    Deleted --> [*]

状态	说明
Created	容器已创建但未启动，分配了文件系统和网络配置
Running	容器主进程（PID 1）正在运行
Paused	容器进程被挂起（SIGSTOP），冻结在内存中不消耗 CPU
Stopped	容器主进程已退出，文件系统和配置仍保留
Deleted	容器被移除，所有资源释放

# 查看容器当前状态
docker inspect --format='{{.State.Status}}' my-container

# 查看容器启动时间、退出码等
docker inspect --format='{{json .State}}' my-container | python3 -m json.tool

2.2.2 容器操作

创建与启动：

# 创建并启动（最常用）
docker run -d --name web -p 8080:80 nginx

# 仅创建（稍后启动）
docker create --name web -p 8080:80 nginx
docker start web

# 启动时指定重启策略
docker run -d --name web --restart=unless-stopped -p 8080:80 nginx

重启策略：

策略	说明
no	默认值，不自动重启
on-failure[:max-retries]	非正常退出时重启，可限制最大重试次数
always	无论退出码如何都重启，Docker Daemon 启动时也会拉起
unless-stopped	类似 always，但手动 docker stop 后不会被 Daemon 自动拉起

停止与删除：

# 优雅停止（先发 SIGTERM，默认等待 10 秒后发 SIGKILL）
docker stop web

# 指定等待时间
docker stop -t 30 web

# 强制停止
docker kill web

# 删除已停止的容器
docker rm web

# 强制删除运行中的容器
docker rm -f web

# 批量删除所有已停止的容器
docker container prune -f

2.2.3 容器日志

# 查看全部日志
docker logs web

# 持续输出日志（类似 tail -f）
docker logs -f web

# 查看最近 100 行
docker logs --tail 100 web

# 显示时间戳
docker logs -t web

# 查看指定时间段的日志
docker logs --since 2024-01-01T00:00:00 --until 2024-01-02T00:00:00 web

# 查看最近 30 分钟的日志
docker logs --since 30m web

日志驱动：

Docker 支持多种日志驱动，默认使用 json-file，日志存储在宿主机的 /var/lib/docker/containers/<container-id>/ 目录下。

# 查看容器使用的日志驱动
docker inspect --format='{{.HostConfig.LogConfig.Type}}' web

# 启动时指定日志驱动和配置（限制单个日志文件最大 10MB，最多保留 3 个文件）
docker run -d --name web \
    --log-driver json-file \
    --log-opt max-size=10m \
    --log-opt max-file=3 \
    nginx

2.2.4 资源监控

# 实时查看容器资源使用（CPU、内存、网络 I/O、磁盘 I/O）
docker stats

# 查看指定容器
docker stats web

# 仅输出一次（非实时，适合脚本采集）
docker stats --no-stream

# 自定义输出格式
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# 查看容器内进程
docker top web

# 查看容器文件系统变更（相对于镜像）
docker diff web
# A = 新增，C = 修改，D = 删除

2.3 容器与宿主机交互

2.3.1 端口映射

将宿主机端口映射到容器端口，使外部可以访问容器内的服务。

graph LR
    USER[外部用户] -->|访问 宿主机:8080| HOST[宿主机]
    HOST -->|转发到 容器:80| CONTAINER[容器 nginx]

# 映射指定端口
docker run -d -p 8080:80 nginx
# 宿主机 8080 → 容器 80

# 映射多个端口
docker run -d -p 8080:80 -p 8443:443 nginx

# 映射到指定 IP（仅本机可访问）
docker run -d -p 127.0.0.1:8080:80 nginx

# 随机映射端口（宿主机自动分配空闲端口）
docker run -d -P nginx

# 查看端口映射关系
docker port web

2.3.2 文件拷贝

# 容器 → 宿主机
docker cp web:/etc/nginx/nginx.conf ./nginx.conf

# 宿主机 → 容器
docker cp ./index.html web:/usr/share/nginx/html/index.html

# 拷贝整个目录
docker cp web:/var/log/nginx ./nginx-logs
docker cp ./config/ web:/app/config/

注意： docker cp 不支持容器间直接拷贝，需以宿主机为中转。

2.3.3 进入容器

# 推荐方式：exec 启动新进程
docker exec -it web bash        # Bash shell
docker exec -it web sh          # Alpine 等轻量镜像用 sh
docker exec -it -u root web bash  # 以 root 身份进入

# 执行单条命令（不进入交互模式）
docker exec web cat /etc/nginx/nginx.conf
docker exec web ls -la /app

# 传递环境变量
docker exec -e DEBUG=true web node /app/script.js

# attach 方式（连接主进程，不推荐）
docker attach web
# Ctrl+P Ctrl+Q 可安全分离，不停止容器
# 直接 Ctrl+C 会停止容器主进程

2.3.4 容器网络基础

每个容器默认分配独立的网络命名空间和 IP 地址。

# 查看容器 IP 地址
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web

# 查看容器网络详情
docker inspect web | grep -A 20 "Networks"

# 从宿主机 ping 容器（需在同一网络）
ping $(docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web)

# 查看容器 DNS 配置
docker exec web cat /etc/resolv.conf

# 查看容器 hosts 文件
docker exec web cat /etc/hosts

---

3. Docker 网络与数据卷

3.1 Docker 网络

3.1.1 网络模式

Docker 提供多种网络模式，适用于不同场景。

graph TB
    subgraph Bridge模式[bridge 默认模式]
        BR[docker0 网桥<br>172.17.0.1]
        C1B[容器1<br>172.17.0.2]
        C2B[容器2<br>172.17.0.3]
        BR --- C1B
        BR --- C2B
    end

    subgraph Host模式[host 模式]
        HN[宿主机网络栈]
        C1H[容器<br>共享宿主机 IP 和端口]
        HN --- C1H
    end

    subgraph None模式[none 模式]
        C1N[容器<br>无网络，仅 loopback]
    end

网络模式	说明	使用场景
bridge	默认模式，容器连接到 docker0 虚拟网桥，通过 NAT 访问外网	大多数单机场景
host	容器直接使用宿主机网络栈，无网络隔离，性能最好	对网络性能要求极高的场景
none	容器无网络接口（仅 loopback），完全隔离	安全敏感的离线计算任务
container	与指定容器共享网络命名空间（IP 和端口）	Sidecar 模式，如日志收集器

# 默认 bridge 模式
docker run -d --name web nginx

# host 模式
docker run -d --network host --name web nginx

# none 模式
docker run -d --network none --name isolated-app myapp

# 与另一个容器共享网络
docker run -d --name app1 nginx
docker run -d --network container:app1 --name app2 busybox

3.1.2 自定义网络

自定义网络提供比默认 bridge 更好的隔离性和 DNS 自动解析（容器间可通过容器名互相访问）。

# 创建自定义 bridge 网络
docker network create my-network

# 指定子网和网关
docker network create --subnet 172.20.0.0/16 --gateway 172.20.0.1 my-network

# 在自定义网络中启动容器
docker run -d --name web --network my-network nginx
docker run -d --name api --network my-network node:18

# 容器间通过名称互访（自定义网络自动提供 DNS）
docker exec api ping web    # ✅ 可直接用容器名
docker exec api curl http://web:80  # ✅ HTTP 访问

# 查看网络列表
docker network ls

# 查看网络详情（含已连接的容器）
docker network inspect my-network

# 删除网络
docker network rm my-network

# 清理所有未使用的网络
docker network prune

3.1.3 容器互联

graph TB
    subgraph 自定义网络 my-network
        WEB[web 容器<br>nginx<br>172.20.0.2]
        API[api 容器<br>node-app<br>172.20.0.3]
        DB[db 容器<br>mysql<br>172.20.0.4]
        WEB -->|curl http://api:3000| API
        API -->|mysql -h db| DB
    end
    USER[外部用户] -->|宿主机:8080| WEB

推荐方式：使用自定义网络

# 创建应用网络
docker network create app-network

# 启动数据库
docker run -d --name db \
    --network app-network \
    -e MYSQL_ROOT_PASSWORD=123456 \
    -e MYSQL_DATABASE=mydb \
    mysql:8.0

# 启动后端 API（通过容器名 db 访问数据库）
docker run -d --name api \
    --network app-network \
    -e DB_HOST=db \
    -e DB_PORT=3306 \
    -p 3000:3000 \
    my-api-app

# 启动前端（通过容器名 api 访问后端）
docker run -d --name web \
    --network app-network \
    -p 8080:80 \
    my-web-app

运行中的容器加入 / 断开网络：

# 将已运行的容器连接到网络
docker network connect app-network existing-container

# 断开网络
docker network disconnect app-network existing-container

3.1.4 网络驱动

驱动	说明	适用场景
bridge	单机桥接网络，容器通过虚拟网桥通信	单机开发和测试
host	移除容器网络隔离，直接使用宿主机网络	高性能网络需求
overlay	跨主机网络，多个 Docker 主机上的容器互通	Docker Swarm / 集群
macvlan	为容器分配真实 MAC 地址，使其在物理网络中可见	需要容器直连物理网络
none	禁用网络	安全隔离场景
ipvlan	类似 macvlan，但共享宿主机 MAC 地址	对 MAC 地址有限制的环境

# 创建 overlay 网络（需先初始化 Swarm）
docker network create --driver overlay my-overlay

# 创建 macvlan 网络
docker network create --driver macvlan \
    --subnet 192.168.1.0/24 \
    --gateway 192.168.1.1 \
    -o parent=eth0 \
    my-macvlan

3.2 Docker 数据卷

3.2.1 数据卷概念

容器的文件系统是临时的，容器删除后数据会丢失。**数据卷（Volume）**是 Docker 管理的持久化存储机制，独立于容器生命周期。

graph LR
    subgraph 容器
        APP[应用进程]
        RW["可写层<br>容器删除即丢失"]
        VOL["/data<br>挂载点"]
    end
    subgraph 宿主机
        DISK["Docker 管理的卷<br>/var/lib/docker/volumes/"]
    end
    APP --> RW
    APP --> VOL
    VOL ---|数据卷| DISK

数据卷 vs 绑定挂载：

特性	数据卷（Volume）	绑定挂载（Bind Mount）
管理方式	Docker 管理	用户指定宿主机路径
存储位置	/var/lib/docker/volumes/	宿主机任意路径
可移植性	高，不依赖宿主机目录结构	低，依赖宿主机具体路径
权限控制	Docker 自动处理	需手动处理权限
性能	最优（Linux 原生）	依赖宿主机文件系统
备份迁移	docker volume 命令管理	需手动操作文件
推荐场景	数据库存储、持久化数据	开发环境代码同步、配置文件

3.2.2 数据卷管理

# 创建数据卷
docker volume create my-data

# 查看所有数据卷
docker volume ls

# 查看数据卷详情（存储路径、创建时间等）
docker volume inspect my-data

# 删除数据卷
docker volume rm my-data

# 清理所有未被容器使用的数据卷
docker volume prune -f

3.2.3 挂载数据卷

使用 -v 或 --mount 参数挂载数据卷到容器中。

# -v 简写语法：卷名:容器路径[:选项]
docker run -d --name db \
    -v mysql-data:/var/lib/mysql \
    mysql:8.0

# --mount 详细语法（推荐，语义更清晰）
docker run -d --name db \
    --mount source=mysql-data,target=/var/lib/mysql \
    mysql:8.0

# 只读挂载
docker run -d --name web \
    -v nginx-conf:/etc/nginx/conf.d:ro \
    nginx

# 卷不存在时自动创建
docker run -d -v auto-created-vol:/data busybox

参数说明： source 是数据卷的名称（即 docker volume create 创建的卷名）；target 是容器内的挂载路径，可以是任意路径，但通常需要指定为应用实际存储数据的目录才能实现持久化。例如 MySQL 的数据目录是 /var/lib/mysql，Nginx 日志目录是 /var/log/nginx，这些路径由镜像内的应用决定，可通过镜像文档或 docker inspect 查看。

3.2.4 绑定挂载

将宿主机目录直接挂载到容器，适合开发环境中实时同步代码。

# 绑定挂载宿主机目录
docker run -d --name web \
    -v /home/user/website:/usr/share/nginx/html \
    -p 8080:80 \
    nginx

# --mount 语法
docker run -d --name web \
    --mount type=bind,source=/home/user/website,target=/usr/share/nginx/html \
    -p 8080:80 \
    nginx

# 只读绑定挂载（容器内无法修改）
docker run -d --name web \
    -v /home/user/nginx.conf:/etc/nginx/nginx.conf:ro \
    nginx

# 开发环境：实时同步代码
docker run -d --name dev-app \
    -v $(pwd)/src:/app/src \
    -p 3000:3000 \
    node:18 npm run dev

路径规则： -v 参数中，以 / 或 ./ 开头的为绑定挂载（宿主机路径），否则为命名数据卷。

3.2.5 数据卷容器

数据卷容器是一个专门提供数据卷给其他容器共享的容器，适用于多个容器间共享数据。

# 创建数据卷容器（不需要运行）
docker create --name data-store \
    -v shared-data:/data \
    busybox

# 其他容器通过 --volumes-from 共享数据卷
docker run -d --name app1 \
    --volumes-from data-store \
    my-app

docker run -d --name app2 \
    --volumes-from data-store \
    my-app

# app1 和 app2 都可以读写 /data 目录，数据实时共享

3.3 数据持久化实战

3.3.1 MySQL 数据持久化

# 创建专用数据卷
docker volume create mysql-data
docker volume create mysql-conf

# 启动 MySQL 并挂载数据卷
docker run -d --name mysql \
    -v mysql-data:/var/lib/mysql \
    -v mysql-conf:/etc/mysql/conf.d \
    -e MYSQL_ROOT_PASSWORD=123456 \
    -e MYSQL_DATABASE=mydb \
    -e MYSQL_USER=app \
    -e MYSQL_PASSWORD=app123 \
    -p 3306:3306 \
    mysql:8.0

# 验证持久化：删除容器后数据不丢失
docker rm -f mysql

# 使用相同的数据卷重新创建容器，数据完整保留
docker run -d --name mysql \
    -v mysql-data:/var/lib/mysql \
    -v mysql-conf:/etc/mysql/conf.d \
    -e MYSQL_ROOT_PASSWORD=123456 \
    -p 3306:3306 \
    mysql:8.0

3.3.2 Nginx 配置持久化

# 先启动临时容器，拷贝默认配置到宿主机
docker run -d --name tmp-nginx nginx
docker cp tmp-nginx:/etc/nginx/nginx.conf ./nginx.conf
docker cp tmp-nginx:/etc/nginx/conf.d ./conf.d
docker cp tmp-nginx:/usr/share/nginx/html ./html
docker rm -f tmp-nginx

# 使用绑定挂载启动 Nginx，方便修改配置
docker run -d --name nginx \
    -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro \
    -v $(pwd)/conf.d:/etc/nginx/conf.d:ro \
    -v $(pwd)/html:/usr/share/nginx/html \
    -v nginx-logs:/var/log/nginx \
    -p 80:80 -p 443:443 \
    nginx

# 修改配置后重载（无需重启容器）
docker exec nginx nginx -s reload

3.3.3 数据备份与恢复

备份数据卷：

# 使用临时容器将数据卷内容打包到宿主机
docker run --rm \
    -v mysql-data:/source:ro \
    -v $(pwd):/backup \
    busybox tar czf /backup/mysql-backup-$(date +%Y%m%d).tar.gz -C /source .

# 说明：
# -v mysql-data:/source:ro  将数据卷只读挂载到临时容器 /source
# -v $(pwd):/backup         将宿主机当前目录挂载到 /backup
# tar czf ...               将 /source 内容压缩到 /backup

恢复数据卷：

# 创建新数据卷
docker volume create mysql-data-restored

# 使用临时容器将备份文件解压到新数据卷
docker run --rm \
    -v mysql-data-restored:/target \
    -v $(pwd):/backup:ro \
    busybox tar xzf /backup/mysql-backup-20240101.tar.gz -C /target

# 使用恢复后的数据卷启动容器
docker run -d --name mysql-restored \
    -v mysql-data-restored:/var/lib/mysql \
    -e MYSQL_ROOT_PASSWORD=123456 \
    -p 3307:3306 \
    mysql:8.0

定时备份脚本示例：

#!/bin/bash
# backup-volumes.sh
BACKUP_DIR="/home/user/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# 备份 MySQL 数据
docker run --rm \
    -v mysql-data:/source:ro \
    -v $BACKUP_DIR:/backup \
    busybox tar czf /backup/mysql-$DATE.tar.gz -C /source .

# 保留最近 7 天的备份
find $BACKUP_DIR -name "mysql-*.tar.gz" -mtime +7 -delete

echo "[$DATE] Backup completed."

---

4. Dockerfile 最佳实践

4.1 Dockerfile 基础

4.1.1 Dockerfile 概念

Dockerfile 是一个文本文件，包含一系列指令（Instruction），用于自动化构建 Docker 镜像。每条指令描述镜像构建的一个步骤，Docker 引擎按顺序执行这些指令，最终生成可运行的镜像。

核心理念：基础设施即代码（Infrastructure as Code）

graph LR
    A[Dockerfile] -->|docker build| B[Docker 镜像]
    B -->|docker run| C[容器实例]
    A -->|版本管理| D[Git 仓库]
    style A fill:#0db7ed,color:#fff
    style B fill:#384d54,color:#fff

Dockerfile 基本结构：

# 基础镜像
FROM node:18-alpine

# 元数据
LABEL maintainer="dev@example.com"
LABEL version="1.0"

# 设置工作目录
WORKDIR /app

# 复制依赖文件
COPY package*.json ./

# 安装依赖
RUN npm install --production

# 复制源代码
COPY . .

# 暴露端口
EXPOSE 3000

# 启动命令
CMD ["node", "server.js"]

4.1.2 基础指令

指令速查表：

指令	作用	语法	是否产生新层
FROM	指定基础镜像，所有指令在此基础上构建；支持多阶段构建中使用 AS 命名阶段	FROM image:tag [AS name]	✅
WORKDIR	设置后续 RUN/CMD/COPY/ADD 等指令的工作目录，目录不存在时自动创建，支持相对路径叠加	WORKDIR /path	❌
COPY	将宿主机构建上下文中的文件/目录复制到镜像中，支持 --chown 指定归属、通配符匹配	COPY [--chown=user] src dest	✅
ADD	功能同 COPY，额外支持自动解压本地 tar 压缩包和从远程 URL 下载文件（推荐优先用 COPY）	ADD src dest	✅
RUN	在构建阶段执行 Shell 命令（如安装依赖、编译代码），每条 RUN 产生一个新的镜像层	RUN command	✅
CMD	设置容器启动时的默认命令和参数，仅最后一条生效；运行时可被 docker run 参数覆盖	CMD ["exec", "arg"]	❌
ENTRYPOINT	设置容器的固定入口命令，与 CMD 配合可实现"命令+默认参数"模式；覆盖需加 --entrypoint	ENTRYPOINT ["exec"]	❌
EXPOSE	声明容器运行时监听的网络端口，仅起文档说明作用，不会自动映射；实际映射需 -p 参数	EXPOSE port[/protocol]	❌
LABEL	为镜像添加键值对形式的元数据（如作者、版本、描述），可通过 docker inspect 查看	LABEL key=value	❌
ENV	设置环境变量，构建阶段和容器运行时均可用；运行时可通过 docker run -e 覆盖	ENV key=value	❌
ARG	定义仅在构建阶段有效的变量，通过 --build-arg 传入；不会持久化到最终镜像中	ARG name[=default]	❌
VOLUME	声明匿名卷挂载点，容器启动时自动创建匿名卷；该指令之后对该目录的 RUN 修改不会保存	VOLUME ["/path"]	❌
USER	切换后续指令和容器运行时的用户身份，提升安全性；切换前需确保用户已创建	USER username	❌
HEALTHCHECK	定义容器健康检查命令，Docker 定期执行并标记容器状态为 healthy/unhealthy	HEALTHCHECK CMD command	❌

---

FROM — 指定基础镜像

每个 Dockerfile 必须以 FROM 开头（ARG 除外），指定构建的基础镜像。

# 使用官方 Node.js 镜像
FROM node:22-alpine

# 使用精简版 Debian 基础镜像
FROM node:22-slim

# 从零开始构建（用于静态编译的二进制）
FROM scratch

WORKDIR — 设置工作目录

设置后续指令的工作目录，目录不存在时自动创建。

WORKDIR /app

# 支持多次切换
WORKDIR /app/src
WORKDIR ../config   # 相对路径，结果为 /app/config

COPY — 复制文件

将宿主机文件/目录复制到镜像中。

# 复制单个文件
COPY package.json /app/

# 复制多个文件
COPY package.json package-lock.json ./

# 复制目录
COPY src/ /app/src/

# 使用通配符
COPY *.conf /etc/nginx/

# --chown 指定文件归属
COPY --chown=node:node . /app/

ADD — 复制并解压

功能类似 COPY，但额外支持自动解压压缩包和远程 URL 下载。

# 自动解压 tar 文件到目标目录
ADD app.tar.gz /app/

# 下载远程文件（不推荐，建议用 RUN curl）
ADD https://example.com/file.txt /app/

⚠️ 最佳实践：除非需要自动解压，否则优先使用 COPY，语义更明确。

RUN — 执行命令

在构建过程中执行命令，每条 RUN 生成一个新的镜像层。

# Shell 形式
RUN apt-get update && apt-get install -y curl

# Exec 形式
RUN ["apt-get", "install", "-y", "vim"]

# 多行书写（推荐）
RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        curl \
        wget \
        git \
    && rm -rf /var/lib/apt/lists/*

CMD — 容器启动命令

指定容器启动时的默认命令，只有最后一条 CMD 生效。

# Exec 形式（推荐）
CMD ["node", "server.js"]

# Shell 形式
CMD node server.js

# 作为 ENTRYPOINT 的默认参数
CMD ["--help"]

ENTRYPOINT — 入口点

设置容器启动时执行的主命令，与 CMD 配合使用。

# 固定入口
ENTRYPOINT ["node", "server.js"]

# ENTRYPOINT + CMD 组合
ENTRYPOINT ["node"]
CMD ["server.js"]
# 运行时可覆盖 CMD：docker run myimage app.js

CMD 与 ENTRYPOINT 对比：

特性	CMD	ENTRYPOINT
用途	默认命令/参数	固定入口命令
可覆盖	docker run 参数直接覆盖	需 --entrypoint 覆盖
多条指令	仅最后一条生效	仅最后一条生效
组合使用	作为 ENTRYPOINT 的默认参数	接收 CMD 作为参数

EXPOSE — 声明端口

声明容器运行时监听的端口（仅作文档说明，不会自动映射）。

EXPOSE 80
EXPOSE 443
EXPOSE 3000/tcp
EXPOSE 5000/udp

LABEL — 元数据

为镜像添加键值对形式的元数据。

LABEL maintainer="dev@example.com"
LABEL version="1.0"
LABEL description="My application"

# 单行写法
LABEL maintainer="dev@example.com" version="1.0"

4.1.3 构建镜像

基本构建命令

# 在 Dockerfile 所在目录构建
docker build -t myapp:1.0 .

# 指定 Dockerfile 路径
docker build -f docker/Dockerfile.prod -t myapp:prod .

# 构建时传入参数
docker build --build-arg NODE_ENV=production -t myapp:prod .

# 不使用缓存
docker build --no-cache -t myapp:1.0 .

构建上下文

docker build 命令末尾的 . 表示构建上下文（Build Context），Docker 会将该目录下所有文件发送给 Docker 引擎。

graph LR
    A[客户端 CLI] -->|发送构建上下文| B[Docker 引擎]
    B -->|逐条执行指令| C[生成镜像层]
    C --> D[最终镜像]
    style B fill:#0db7ed,color:#fff

# 当前目录作为上下文
docker build -t myapp .

# 指定其他目录作为上下文
docker build -t myapp /path/to/context

# 使用 URL 作为上下文
docker build -t myapp https://github.com/user/repo.git

查看构建过程

# 查看镜像构建历史
docker history myapp:1.0

# 输出示例
IMAGE          CREATED        CREATED BY                                      SIZE
a1b2c3d4e5f6   2 hours ago   CMD ["node" "server.js"]                         0B
b2c3d4e5f6a1   2 hours ago   EXPOSE map[3000/tcp:{}]                          0B
c3d4e5f6a1b2   2 hours ago   COPY dir:xxx in /app                             5.2MB
d4e5f6a1b2c3   2 hours ago   RUN npm install --production                     45MB
e5f6a1b2c3d4   2 hours ago   COPY file:xxx in /app/package*.json              120kB
f6a1b2c3d4e5   2 hours ago   WORKDIR /app                                     0B

4.1.4 镜像标签

标签用于标识镜像的不同版本，格式为 仓库名:标签。

# 构建时指定标签
docker build -t myapp:1.0 .
docker build -t myapp:latest .

# 给已有镜像打标签
docker tag myapp:1.0 myapp:stable
docker tag myapp:1.0 registry.example.com/myapp:1.0

# 同时打多个标签
docker build -t myapp:1.0 -t myapp:latest .

标签策略建议：

策略	示例	适用场景
语义化版本	myapp:1.2.3	正式发布
Git 提交哈希	myapp:a1b2c3d	CI/CD 自动构建
日期标签	myapp:20240101	定期构建
环境标签	myapp:prod, myapp:dev	多环境部署
latest	myapp:latest	默认标签（谨慎使用）

⚠️ 注意：latest 标签不代表"最新版本"，它只是默认标签名。建议始终使用明确的版本标签。

---

4.2 Dockerfile 进阶

4.2.1 ENV / ARG — 变量管理

ENV — 环境变量

设置容器运行时的环境变量，在构建阶段和容器运行时均可用。

# 设置单个变量
ENV NODE_ENV=production

# 设置多个变量
ENV APP_HOME=/app \
    APP_PORT=3000 \
    LOG_LEVEL=info

# 在后续指令中引用
WORKDIR $APP_HOME
EXPOSE $APP_PORT

# 运行时覆盖环境变量
docker run -e NODE_ENV=development myapp
docker run --env-file .env myapp

ARG — 构建参数

定义构建时使用的变量，仅在 docker build 过程中有效，不会保留到运行时。

# 定义构建参数（可设默认值）
ARG NODE_VERSION=18
ARG APP_ENV=production

# 在 FROM 之前使用 ARG
ARG BASE_IMAGE=node:18-alpine
FROM $BASE_IMAGE

# 在构建过程中引用
ARG APP_ENV
RUN echo "Building for: $APP_ENV"

# 构建时传入参数
docker build --build-arg NODE_VERSION=20 --build-arg APP_ENV=staging -t myapp .

ENV vs ARG 对比：

特性	ENV	ARG
构建时可用	✅	✅
运行时可用	✅	❌
可被 docker run -e 覆盖	✅	❌
可被 --build-arg 覆盖	❌	✅
持久化到镜像	✅	❌

⚠️ 安全提示：不要用 ARG 传递密码等敏感信息，docker history 可以查看到 ARG 的值。

4.2.2 VOLUME — 数据卷声明

在 Dockerfile 中声明匿名卷挂载点，容器启动时自动创建匿名卷。

# 声明单个卷
VOLUME /data

# 声明多个卷
VOLUME ["/data", "/logs", "/config"]

VOLUME 指令的行为：

FROM mysql:8.0

# 声明数据目录为卷
VOLUME /var/lib/mysql

# 注意：VOLUME 之后对该目录的修改不会生效！
RUN echo "test" > /var/lib/mysql/test.txt  # ❌ 无效

# 运行时会自动创建匿名卷
docker run -d mysql:8.0
docker volume ls
# DRIVER    VOLUME NAME
# local     a1b2c3d4e5f6...  （自动生成的匿名卷）

# 推荐在运行时显式挂载命名卷
docker run -d -v mysql-data:/var/lib/mysql mysql:8.0

⚠️ 注意：VOLUME 指令之后，对该目录的 RUN 操作都不会被持久化到镜像中。

4.2.3 HEALTHCHECK — 健康检查

定义容器的健康检查机制，Docker 会定期执行检查命令判断容器是否健康。

# 基本用法
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:3000/health || exit 1

参数说明：

参数	默认值	说明
--interval	30s	检查间隔时间
--timeout	30s	单次检查超时时间
--start-period	0s	容器启动初始化等待时间
--retries	3	连续失败多少次标记为 unhealthy

不同应用类型的健康检查示例：

# Web 应用
HEALTHCHECK --interval=15s --timeout=3s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

# 数据库
HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=5 \
    CMD mysqladmin ping -h localhost -u root -p$MYSQL_ROOT_PASSWORD || exit 1

# Redis
HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
    CMD redis-cli ping | grep -q PONG || exit 1

# 无 curl 环境，使用 wget
HEALTHCHECK --interval=15s --timeout=3s \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

# 禁用健康检查（如果基础镜像已定义）
HEALTHCHECK NONE

查看健康状态：

# 查看容器健康状态
docker ps
# STATUS 列会显示 (healthy) 或 (unhealthy)

# 查看详细健康检查日志
docker inspect --format='{{json .State.Health}}' my-container | jq

4.2.4 多阶段构建

多阶段构建允许在一个 Dockerfile 中使用多个 FROM 指令，每个 FROM 开启一个新的构建阶段。最终镜像只包含最后一个阶段的内容，从而大幅减小镜像体积。

graph LR
    subgraph 阶段1-构建
        A[完整 SDK/编译工具] --> B[编译产物]
    end
    subgraph 阶段2-运行
        C[精简运行时] --> D[仅复制产物]
    end
    B -->|COPY --from| D
    style A fill:#e74c3c,color:#fff
    style C fill:#27ae60,color:#fff

Node.js 前端应用示例

# ========== 阶段1：构建 ==========
FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# ========== 阶段2：运行 ==========
FROM nginx:alpine AS production

# --from=builder 表示从名为 "builder" 的构建阶段（即上方 FROM ... AS builder）中复制文件
# 只取构建产物，不携带源码和 node_modules，大幅缩减最终镜像体积
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

多阶段构建体积对比（Node.js）：

应用类型	单阶段镜像	多阶段镜像	说明
纯前端 SPA/SSG	~1.2GB	~25MB	最终只需 nginx + 静态文件，无需 Node 运行时
SSR 应用（如 Vike）	~1.2GB	~200-300MB	仍需 Node 运行时 + 生产依赖，但去掉了 devDependencies 和源码

---

4.3 Dockerfile 最佳实践

4.3.1 减少镜像层数

每条 RUN、COPY、ADD 指令都会创建一个新的镜像层。合并指令可以减少层数，缩小镜像体积。

❌ 不推荐 — 过多层数：

RUN apt-get update
RUN apt-get install -y curl
RUN apt-get install -y wget
RUN apt-get install -y git
RUN rm -rf /var/lib/apt/lists/*

✅ 推荐 — 合并为单层：

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        curl \
        wget \
        git \
    && rm -rf /var/lib/apt/lists/*

其他减少层数的技巧：

# ❌ 多条 ENV
ENV APP_NAME=myapp
ENV APP_PORT=3000
ENV LOG_LEVEL=info

# ✅ 合并 ENV
ENV APP_NAME=myapp \
    APP_PORT=3000 \
    LOG_LEVEL=info

# ❌ 多条 LABEL
LABEL maintainer="dev@example.com"
LABEL version="1.0"

# ✅ 合并 LABEL
LABEL maintainer="dev@example.com" \
      version="1.0"

4.3.2 利用构建缓存

Docker 按指令顺序构建，如果某层的输入未改变，会直接使用缓存。将变化频率低的指令放在前面，变化频率高的放在后面。

❌ 不推荐 — 源码变动导致依赖重装：

FROM node:18-alpine
WORKDIR /app
COPY . .                  # 任何文件改变都会使缓存失效
RUN npm install           # 每次都要重新安装依赖
CMD ["node", "server.js"]

✅ 推荐 — 分离依赖安装与源码复制：

FROM node:22-alpine
WORKDIR /app

# 第1步：仅复制依赖描述文件（变化少）
COPY package.json ./

# 第2步：安装依赖（仅依赖文件变化时重新执行）
# 注意：跨平台（如 Windows 开发 → Linux 容器）时不要复制 package-lock.json
# 否则 npm ci 会按 lock 文件安装，导致缺少 Linux 平台的可选依赖
RUN npm install --production

# 第3步：复制源代码（变化频繁，放最后）
COPY . .

CMD ["node", "server.js"]

graph TB
    A["COPY package.json（缓存命中 ✅）"] --> B["RUN npm install（缓存命中 ✅）"]
    B --> C["COPY . .（代码改变，缓存失效 ❌）"]
    C --> D["CMD ...（重新执行）"]
    style A fill:#27ae60,color:#fff
    style B fill:#27ae60,color:#fff
    style C fill:#e74c3c,color:#fff

4.3.3 .dockerignore

.dockerignore 文件用于排除不需要发送到构建上下文的文件，减小上下文体积，加快构建速度，避免敏感信息泄露。

# .dockerignore

# 版本控制
.git
.gitignore

# 依赖目录
node_modules
vendor
__pycache__

# 构建产物
dist
build
*.jar
target

# IDE 与编辑器
.vscode
.idea
*.swp
*.swo

# 环境与配置
.env
.env.local
.env.*.local
*.pem
*.key

# Docker 相关
Dockerfile*
docker-compose*.yml
.dockerignore

# 文档与测试
README.md
docs/
test/
tests/
coverage/

# 系统文件
.DS_Store
Thumbs.db

# 日志
*.log
logs/

效果对比：

# 无 .dockerignore
Sending build context to Docker daemon  450MB  ← 包含 node_modules 等

# 有 .dockerignore
Sending build context to Docker daemon  2.5MB  ← 仅必要文件

4.3.4 选择基础镜像

选择合适的基础镜像对镜像体积和安全性影响巨大。

常见基础镜像对比：

基础镜像	体积	包管理器	适用场景
ubuntu:22.04	~77MB	apt	需要完整 Linux 环境
debian:bookworm-slim	~74MB	apt	通用场景（精简版）
alpine:3.19	~7MB	apk	追求极致精简
distroless	~2-20MB	无	仅运行时，安全优先
scratch	0MB	无	静态编译的二进制

Node.js 镜像变体：

node:18          # ~1GB，包含完整开发工具
node:18-slim     # ~200MB，精简版 Debian
node:18-alpine   # ~170MB，基于 Alpine Linux

选择建议：

# 开发/调试阶段 — 功能完整
FROM node:18

# 生产环境 — 推荐 slim
FROM node:18-slim

# 极致精简 — 使用 Alpine（注意 musl libc 兼容性）
FROM node:18-alpine

# Go/Rust 等静态编译 — 使用 scratch
FROM scratch

4.3.5 使用非 root 用户

默认情况下容器以 root 用户运行，这是一个安全隐患。应创建并切换到普通用户。

FROM node:18-alpine

# 创建应用用户和组
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

COPY package*.json ./
RUN npm ci --production

# 复制文件并指定归属
COPY --chown=appuser:appgroup . .

# 切换到非 root 用户
USER appuser

EXPOSE 3000
CMD ["node", "server.js"]

验证用户身份：

# 进入容器查看当前用户
docker exec -it my-container whoami
# appuser

# 查看进程运行用户
docker exec -it my-container ps aux

⚠️ 注意：USER 指令之前的 RUN 命令仍以 root 执行，因此安装软件包等操作应在 USER 之前完成。

---

4.4 镜像优化

4.4.1 镜像体积优化

清理不必要的文件

# ❌ 残留缓存
RUN apt-get update && apt-get install -y curl

# ✅ 同一层中清理
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

# ✅ npm 清理缓存
RUN npm install --production && npm cache clean --force

# ✅ apk 不保留缓存
RUN apk add --no-cache curl wget

使用 .dockerignore 排除无关文件

参见 4.3.3 .dockerignore。

多阶段构建

参见 4.2.4 多阶段构建。

压缩与合并层

# 使用 --squash 合并层（实验性功能）
docker build --squash -t myapp:squashed .

# 导出再导入压缩镜像
docker export $(docker create myapp:1.0) | docker import - myapp:compressed

优化效果示例：

优化手段	原始体积	优化后	减少
slim 替代完整镜像	1.0GB	200MB	80%
alpine 替代 slim	200MB	170MB	15%
多阶段构建	1.2GB	25MB	98%
清理包管理缓存	350MB	280MB	20%
.dockerignore	构建上下文 450MB	2.5MB	99%

4.4.2 镜像安全扫描

定期扫描镜像中的已知漏洞，是生产环境的必要步骤。

Docker Scout（官方工具）

# 扫描本地镜像
docker scout cves myapp:1.0

# 快速概览
docker scout quickview myapp:1.0

# 查看改进建议
docker scout recommendations myapp:1.0

Trivy（开源工具，推荐）

# 安装 Trivy
docker run --rm aquasec/trivy --version

# 扫描镜像漏洞
docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    aquasec/trivy image myapp:1.0

# 仅显示高危和严重漏洞
docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    aquasec/trivy image --severity HIGH,CRITICAL myapp:1.0

# 输出 JSON 格式（适合 CI/CD）
docker run --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    aquasec/trivy image -f json -o results.json myapp:1.0

CI/CD 集成示例

# GitHub Actions 示例
- name: Run Trivy vulnerability scanner
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myapp:${{ github.sha }}
    format: 'table'
    exit-code: '1'                # 发现漏洞时失败
    severity: 'CRITICAL,HIGH'

安全最佳实践清单：

• ✅ 使用官方/可信基础镜像
• ✅ 固定镜像版本标签（不用 latest）
• ✅ 定期更新基础镜像
• ✅ 使用非 root 用户运行
• ✅ 不在镜像中存储敏感信息
• ✅ 使用多阶段构建减少攻击面
• ✅ 在 CI/CD 中集成安全扫描

4.4.3 镜像分层优化

理解 Docker 镜像的分层机制，有助于写出高效的 Dockerfile。

镜像层原理

graph TB
    subgraph 镜像分层
        L1["Layer 1: FROM alpine（基础镜像层）"]
        L2["Layer 2: RUN apk add...（安装依赖）"]
        L3["Layer 3: COPY package.json（依赖描述）"]
        L4["Layer 4: RUN npm install（安装依赖）"]
        L5["Layer 5: COPY . .（应用代码）"]
        L1 --> L2 --> L3 --> L4 --> L5
    end
    style L1 fill:#384d54,color:#fff
    style L5 fill:#e74c3c,color:#fff

• 每一层都是只读的，通过联合文件系统（UnionFS）叠加
• 容器运行时在最顶层添加一个可写层
• 层是可共享的：多个镜像可复用相同的底层

查看镜像层

# 查看各层大小
docker history myapp:1.0

# 使用 dive 工具深入分析（推荐）
docker run --rm -it \
    -v /var/run/docker.sock:/var/run/docker.sock \
    wagoodman/dive myapp:1.0

dive 可以交互式地浏览每一层的文件变化，发现不必要的大文件。

分层优化策略

1. 将变化频率相同的操作放在同一层：

# ✅ 系统依赖（变化很少）— 放在前面
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# ✅ 应用依赖（偶尔变化）— 放在中间
COPY package.json package-lock.json ./
RUN npm ci --production

# ✅ 应用代码（经常变化）— 放在最后
COPY . .

2. 避免在高层删除低层文件：

# ❌ 文件仍保留在 Layer 2 中，镜像体积不会减小
COPY large-file.tar.gz /tmp/       # Layer 2: +500MB
RUN tar xzf /tmp/large-file.tar.gz && rm /tmp/large-file.tar.gz  # Layer 3

# ✅ 在同一层完成下载、解压、清理
RUN curl -O https://example.com/large-file.tar.gz \
    && tar xzf large-file.tar.gz \
    && rm large-file.tar.gz

3. 合理利用层共享：

# 团队多个项目使用相同基础层
# Dockerfile.base
FROM node:22-alpine
RUN apk add --no-cache make g++

# Dockerfile.app1 / Dockerfile.app2
FROM myteam/base:1.0    # 共享基础层
COPY . /app

完整优化示例对比：

# ========== 优化前 ==========
FROM node:18
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/server.js"]
# 镜像体积：~1.4GB

# ========== 优化后 ==========
FROM node:18-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
RUN addgroup -S app && adduser -S app -G app
COPY --from=builder --chown=app:app /app/dist ./dist
COPY --from=builder --chown=app:app /app/node_modules ./node_modules
COPY --from=builder --chown=app:app /app/package.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=15s --timeout=3s \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]
# 镜像体积：~180MB

---

5. Docker Compose

5.1 Docker Compose 基础

5.1.1 Compose 概念

Docker Compose 是一个用于定义和运行多容器应用的工具。通过一个 YAML 文件描述所有服务、网络和数据卷，一条命令即可启动整个应用栈。

核心价值：

• 一个文件定义整个应用架构
• 一条命令启动/停止所有服务
• 服务间自动网络互通（通过服务名访问）
• 环境一致性（开发、测试、生产）

graph TB
    A[docker-compose.yml] -->|docker compose up| B[Docker Compose]
    B --> C[Service: app]
    B --> D[Service: nginx]
    B --> E[Service: db]
    B --> F[Network: 自动创建]
    B --> G[Volume: 数据持久化]
    style A fill:#0db7ed,color:#fff
    style B fill:#384d54,color:#fff

5.1.2 docker-compose.yml

docker-compose.yml 是 Compose 的核心配置文件，使用 YAML 格式描述应用的服务、网络和数据卷。

基本结构：

# 服务定义
services:
  # 服务名（自定义，同时作为容器间的 DNS 名称）
  web:
    image: nginx:alpine          # 使用镜像
    ports:
      - "80:80"                  # 端口映射 宿主机:容器

  app:
    build: .                     # 从 Dockerfile 构建
    ports:
      - "3000:3000"
    environment:                 # 环境变量
      - NODE_ENV=production

  db:
    image: mysql:8.0
    volumes:                     # 数据卷挂载
      - db-data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=123456

# 数据卷定义
volumes:
  db-data:

# 网络定义（可选，Compose 会自动创建默认网络）
networks:
  app-net:

常用配置项速查：

配置项	作用	示例
image	指定使用的 Docker 镜像，Compose 直接拉取该镜像创建容器，不需要本地 Dockerfile	image: nginx:alpine
build	从本地 Dockerfile 构建镜像；可指定构建上下文目录和 Dockerfile 文件名	build: . 或 build: { context: ., dockerfile: Dockerfile }
ports	将容器端口映射到宿主机，格式 宿主机端口:容器端口，外部可通过宿主机端口访问服务	ports: ["80:80", "443:443"]
expose	仅在 Compose 内部网络暴露端口，供其他服务访问，不映射到宿主机，外部无法直接访问	expose: ["3000"]
environment	直接定义容器的环境变量，容器内应用可通过 process.env 读取	environment: [NODE_ENV=production]
env_file	从外部 .env 文件批量加载环境变量，适合管理大量配置项，避免在 yml 中硬编码敏感信息	env_file: .env
volumes	挂载数据卷或宿主机目录到容器内，实现数据持久化；容器删除后数据仍保留	volumes: [./data:/app/data]
depends_on	声明服务间的启动依赖关系，确保被依赖的服务先启动；可配合 condition 等待服务健康	depends_on: [db, redis]
restart	定义容器异常退出时的重启策略：no（不重启）、always（总是重启）、unless-stopped（除手动停止外自动重启）	restart: unless-stopped
networks	将服务加入指定网络，同一网络内的服务可通过服务名互相访问；不同网络间相互隔离	networks: [app-net]
deploy	部署相关配置，如副本数（replicas）、资源限制（resources）、更新策略（update_config）	deploy: { replicas: 3 }
command	覆盖 Dockerfile 中定义的 CMD，指定容器启动时执行的命令	command: ["node", "server.js"]
healthcheck	定义容器的健康检查命令，Docker 定期执行并标记容器状态，可配合 depends_on.condition 实现依赖等待	healthcheck: { test: ["CMD", "curl", "-f", "http://localhost"] }

5.1.3 基本命令

# ========== 启动与停止 ==========

# 启动所有服务（后台运行）
docker compose up -d

# 构建并启动（代码有改动时加 --build）
docker compose up -d --build

# 停止所有服务
docker compose stop

# 停止并删除容器、网络
docker compose down

# 停止并删除容器、网络、数据卷（⚠️ 会删除持久化数据）
docker compose down -v

# ========== 查看状态 ==========

# 查看运行中的服务
docker compose ps

# 查看服务日志
docker compose logs

# 实时跟踪日志
docker compose logs -f

# 查看指定服务日志
docker compose logs -f app

# ========== 服务管理 ==========

# 重启指定服务
docker compose restart app

# 进入服务容器
docker compose exec app sh

# 在服务中执行一次性命令
docker compose run --rm app node -v

# 水平扩展服务实例
docker compose up -d --scale app=5

# ========== 构建相关 ==========

# 仅构建镜像（不启动）
docker compose build

# 不使用缓存重新构建
docker compose build --no-cache

# 拉取配置中的镜像
docker compose pull

常用命令速查表：

命令	作用
docker compose up -d	后台启动所有服务
docker compose up -d --build	重新构建并启动
docker compose down	停止并清理容器和网络
docker compose ps	查看服务状态
docker compose logs -f	实时查看日志
docker compose exec <服务名> sh	进入容器
docker compose restart <服务名>	重启指定服务
docker compose --scale <服务名>=N	扩展到 N 个实例

---

5.2 服务编排

5.2.1 多服务应用

一个典型的 Web 应用通常包含多个服务协同工作：

graph LR
    User[用户] --> Nginx[Nginx 反向代理]
    Nginx --> App1[App 实例1]
    Nginx --> App2[App 实例2]
    App1 --> DB[(MySQL)]
    App2 --> DB
    App1 --> Cache[(Redis)]
    App2 --> Cache
    style Nginx fill:#009639,color:#fff
    style DB fill:#4479A1,color:#fff
    style Cache fill:#DC382D,color:#fff

services:
  # 反向代理
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app
    restart: unless-stopped

  # 应用服务
  app:
    build: .
    expose:
      - "3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=db
      - REDIS_HOST=cache
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    restart: unless-stopped

  # 数据库
  db:
    image: mysql:8.0
    volumes:
      - db-data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=123456
      - MYSQL_DATABASE=myapp
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  # 缓存
  cache:
    image: redis:7-alpine
    volumes:
      - cache-data:/data
    restart: unless-stopped

volumes:
  db-data:
  cache-data:

5.2.2 服务依赖

depends_on 控制服务启动顺序，支持两种写法：

简单依赖（仅控制启动顺序）：

services:
  app:
    depends_on:
      - db        # db 先启动，但不等它就绪
      - cache

条件依赖（等待服务就绪）：

services:
  app:
    depends_on:
      db:
        condition: service_healthy    # 等 db 健康检查通过
      cache:
        condition: service_started    # 等 cache 容器启动即可

条件	说明
service_started	容器启动即满足（默认）
service_healthy	容器健康检查通过（需配置 healthcheck）
service_completed_successfully	容器执行完毕且退出码为 0

⚠️ 注意：depends_on 只控制启动顺序，不保证服务内的应用已完全就绪。建议配合 healthcheck 使用 condition: service_healthy。

5.2.3 环境变量

Compose 支持多种方式注入环境变量：

方式一：直接在 yml 中定义

services:
  app:
    environment:
      - NODE_ENV=production
      - PORT=3000
      - DB_HOST=db

方式二：使用 .env 文件

# .env（与 docker-compose.yml 同目录）
NODE_ENV=production
PORT=3000
DB_HOST=db
DB_PASSWORD=secret123

services:
  app:
    env_file:
      - .env

方式三：在 yml 中引用宿主机环境变量

services:
  app:
    environment:
      - NODE_ENV=${NODE_ENV:-production}    # 默认值 production
      - DB_PASSWORD=${DB_PASSWORD}          # 从宿主机环境变量读取

优先级（高 → 低）：

1. docker compose run -e 命令行参数
2. environment 字段直接定义
3. env_file 文件
4. Dockerfile 中的 ENV

5.2.4 网络和数据卷

网络

Compose 会自动为项目创建一个默认网络，所有服务自动加入，可通过服务名互相访问。

services:
  app:
    # 可通过 "db" 访问数据库，如 mysql://db:3306
    # 可通过 "cache" 访问 Redis，如 redis://cache:6379
    environment:
      - DB_HOST=db
      - REDIS_HOST=cache

  db:
    image: mysql:8.0

  cache:
    image: redis:7-alpine

自定义网络（隔离不同服务组）：

services:
  nginx:
    networks:
      - frontend        # nginx 只在前端网络

  app:
    networks:
      - frontend        # app 同时在前端和后端网络
      - backend

  db:
    networks:
      - backend          # db 只在后端网络（nginx 无法直接访问）

networks:
  frontend:
  backend:

graph TB
    subgraph frontend 网络
        Nginx[nginx]
        App[app]
    end
    subgraph backend 网络
        App2[app]
        DB[(db)]
    end
    Nginx --> App
    App2 --> DB
    style Nginx fill:#009639,color:#fff
    style DB fill:#4479A1,color:#fff

数据卷

services:
  db:
    volumes:
      # 命名卷 — 由 Docker 管理，持久化存储
      - db-data:/var/lib/mysql

      # 绑定挂载 — 映射宿主机目录
      - ./init-sql:/docker-entrypoint-initdb.d:ro

      # 只读挂载（:ro）
      - ./config/my.cnf:/etc/mysql/conf.d/my.cnf:ro

volumes:
  db-data:              # 声明命名卷
    driver: local       # 默认驱动

挂载类型	语法	适用场景
命名卷	vol-name:/container/path	数据库数据、持久化文件
绑定挂载	./host/path:/container/path	配置文件、初始化脚本
只读挂载	./path:/container/path:ro	配置文件（防止容器修改）

---

5.3 Compose 实战

5.3.1 vike-zyh-test 项目部署

以当前项目为例，使用 Docker Compose 部署 Vike SSR 应用 + Nginx 负载均衡。

项目架构：

graph LR
    User[用户 :80] --> Nginx[Nginx 反向代理]
    Nginx --> App1[vike-app 实例1 :3000]
    Nginx --> App2[vike-app 实例2 :3000]
    Nginx --> App3[vike-app 实例3 :3000]
    style Nginx fill:#009639,color:#fff
    style App1 fill:#0db7ed,color:#fff
    style App2 fill:#0db7ed,color:#fff
    style App3 fill:#0db7ed,color:#fff

docker-compose.yml：

services:
  # 应用服务（可水平扩展多个实例）
  app:
    build: .
    environment:
      - NODE_ENV=production
      - PORT=3000
    # 不对外暴露端口，由 nginx 统一转发
    expose:
      - "3000"
    restart: unless-stopped
    deploy:
      replicas: 3  # 启动 3 个容器实例

  # Nginx 负载均衡
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app
    restart: unless-stopped

nginx.conf：

events {
    worker_connections 1024;
}

http {
    # 上游服务组 — Docker Compose DNS 自动解析所有 app 实例
    upstream app_servers {
        # 默认轮询策略，请求依次分配到每个容器
        server app:3000;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://app_servers;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

关键点：upstream 中 server app:3000 的 app 是 Compose 服务名。Docker 内置 DNS 会将 app 解析为所有 app 容器的 IP，Nginx 自动轮询分发请求。

部署与管理：

# 1. 构建并启动
docker compose up -d --build

# 2. 查看服务状态
docker compose ps
# NAME            SERVICE   STATUS    PORTS
# project-app-1   app      running   3000/tcp
# project-app-2   app      running   3000/tcp
# project-app-3   app      running   3000/tcp
# project-nginx-1 nginx    running   0.0.0.0:80->80/tcp

# 3. 访问应用
# 浏览器打开 http://localhost

# 4. 查看日志（观察请求分配到不同实例）
docker compose logs -f app

# 5. 动态扩缩容
docker compose up -d --scale app=5    # 扩展到 5 个实例
docker compose up -d --scale app=2    # 缩减到 2 个实例

# 6. 更新部署（代码改动后）
docker compose up -d --build

# 7. 停止并清理
docker compose down

5.3.2 GitHub Actions + Docker Compose 自动部署

推送代码 → GitHub Actions 构建镜像并推送到本地 Registry → 服务器 Docker Compose 拉取部署。

graph LR
    A[git push] --> B[GitHub Actions]
    B --> C[构建镜像]
    C --> D[推送到本地 Registry :5000]
    D --> E[SSH 服务器]
    E --> F["docker compose pull & up"]
    style B fill:#2088FF,color:#fff
    style D fill:#0db7ed,color:#fff

前置条件：服务器上启动本地 Registry（本地启动测试的镜像仓库，用于模拟）

docker run \
    -d \                          # 后台运行容器
    -p 5000:5000 \                # 将宿主机 5000 端口映射到容器 5000 端口（Registry 默认端口）
    --name registry \             # 容器命名为 registry，方便后续管理
    --restart unless-stopped \    # 异常退出自动重启，手动 stop 除外
    registry:2                    # 使用官方 Registry v2 镜像

步骤一：服务器上的 docker-compose.prod.yml

# /opt/vike-zyh-test/docker-compose.prod.yml
services:
  app:
    image: localhost:5000/vike-zyh-test:latest
    environment:
      - NODE_ENV=production
      - PORT=3000
    expose:
      - "3000"
    restart: unless-stopped
    deploy:
      replicas: 3

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app
    restart: unless-stopped

步骤二：GitHub Actions 工作流

# .github/workflows/deploy.yml
name: Build and Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:       # 手动触发（Actions 页面点击 "Run workflow"）

env:
  REGISTRY: ${{ secrets.SERVER_HOST }}:5000
  IMAGE_NAME: vike-zyh-test

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # 配置 Docker 允许推送到 HTTP 仓库（本地 Registry 无 HTTPS）
      - name: Configure insecure registry
        run: |
          echo '{ "insecure-registries": ["${{ env.REGISTRY }}"] }' | sudo tee /etc/docker/daemon.json
          sudo systemctl restart docker

      - name: Build image
        run: docker build -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest .

      - name: Push to registry
        run: docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

      - name: Deploy to server
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            cd /opt/vike-zyh-test
            docker compose -f docker-compose.prod.yml pull
            docker compose -f docker-compose.prod.yml up -d
            docker image prune -f

步骤三：配置 GitHub Secrets

在仓库 Settings → Secrets and variables → Actions 中添加：

Secret 名称	值	说明
SERVER_HOST	192.168.1.100	部署服务器的公网/局域网 IP（同时运行 Registry），不是 GitHub 账号
SERVER_USER	Administrator	部署服务器的 SSH 登录用户名，不是 GitHub 用户名
SERVER_SSH_KEY	私钥文件内容	用于 SSH 登录服务器的私钥（cat ~/.ssh/id_rsa），不是 GitHub 的 key

本地模拟推送并启动服务 原本正常应该使用action进行推送，但是因为没有测试的镜像仓库，因此本地启动了一个测试镜像仓库，并模拟action中的构建和推送

# 模拟：
# 1. 构建镜像
docker build -t localhost:5000/vike-zyh-test:latest .
# 2. 推送到本地 Registry
docker push localhost:5000/vike-zyh-test:latest


# 到服务器上部署：
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

完结撒花~~~

在开发新项目中。我们面临一个具体场景：纯预览展示的协议文档需要动态填充用户数据。这些协议本身是静态HTML模板，但其中包含大量需要根据具体业务数据动态替换的字段，如客户姓名、贷款金额、银行信息等。

技术挑战

1. 多环境适配：协议模板需要在开发、测试、生产不同环境中运行
2. 数据安全：敏感数据（如银行卡号、身份证号）需要安全获取和展示
3. 动态替换：协议中的占位符需要精准、高效地被实际数据替换
4. 兼容性：方案需要支持多种浏览器环境和模块系统

解决方案架构

核心设计理念

我们设计了一个SignatureDataService类，作为数据获取和模板填充的核心服务。该方案采用以下关键设计：

1. 环境智能判断：自动识别运行环境，配置对应的API端点
2. 数据隔离存储：使用本地存储管理业务入口标识(entryCode)
3. 模板引擎：轻量级占位符替换机制
4. 单例模式：确保全局唯一的数据服务实例

环境配置策略

javascript

function getEnvConfig() {
  const hostname = window.location.hostname;
  const href = window.location.href;

  // 开发环境
  if (hostname === 'localhost') {
    return {
      apiBaseUrl: 'http://localhost:8080/api',
      env: 'development'
    };
  }

  // 测试环境
  if (href.includes('.test.') || hostname.includes('test')) {
    return {
      apiBaseUrl: '测试环境地址',
      env: 'testcloud'
    };
  }

  // 生产环境
  return {
    apiBaseUrl: ' 生产环境地址',
    env: 'prodcloud'
  };
}

核心服务类

SignatureDataService类封装了完整的数据处理流程：

1. 数据获取

javascript

async fetchSignatureData() {
  const entryCode = this.getEntryCode();
  if (!entryCode) return null;
  
  const apiUrl = `${this.config.apiBaseUrl}/signature/getSignatureParams`;
  const response = await fetch(`${apiUrl}?entryCode=${encodeURIComponent(entryCode)}`);
  // ... 处理响应
}

2. 模板填充

javascript

fillTemplate(data) {
  if (!data) return;
  
  let content = document.body.innerHTML;
  const fields = {
    'bankName': data.bankName || '',
    'bankCardNo': data.bankCardNo || '',
    // ... 其他30+字段
  };
  
  // 正则表达式替换所有${fieldName}占位符
  Object.keys(fields).forEach(key => {
    const placeholder = `${${key}}`;
    const regex = new RegExp(
      placeholder.replace(/$/g, '\$').replace(/{/g, '\{').replace(/}/g, '\}'),
      'g'
    );
    content = content.replace(regex, this.escapeHtml(fields[key]));
  });
  
  document.body.innerHTML = content;
}

3. 安全防护

javascript

escapeHtml(text) {
  const div = document.createElement('div');
  div.textContent = text;
  return div.innerHTML;
}

支持的数据字段

系统支持超过30个业务字段的自动填充，涵盖：

• 客户信息：customerName, cardNum, phoneNum
• 贷款信息：loanAmount, period, totalInterest
• 车辆信息：carModel, chassisNo, carColor
• 公司信息：companyName, companyUsci, companyAddress
• 金额相关：所有金额字段同时提供数字和中文大写形式

使用方式

1. HTML模板准备

协议模板中使用${fieldName}格式的占位符：

html

<div class="contract-section">
  <p>甲方（借款人）：${customerName}</p>
  <p>身份证号：${cardNum}</p>
  <p>贷款金额：${loanAmount}元（${loanAmountWord}）</p>
</div>

2. 页面初始化

javascript

// 方式一：使用默认配置
const service = window.SignatureDataService.getSignatureService();
service.initPage();

// 方式二：自定义配置
const service = new window.SignatureDataService.SignatureDataService({
  storageKey: 'customEntryCode'
});
service.initPage();

// 方式三：直接获取数据
const data = await window.SignatureDataService.fetchSignatureData();

技术优势

1. 无框架依赖

纯JavaScript实现，不依赖React、Vue等框架，适用于各种传统项目

2. 性能优化

• 单例模式减少内存开销
• 批量正则替换提升渲染效率
• 按需加载数据

3. 安全考虑

• HTML转义防止XSS攻击
• 敏感数据本地存储隔离
• HTTPS环境自动适配

4. 扩展性

• 模块化设计，易于添加新字段
• 支持CommonJS和浏览器全局两种导出方式
• 配置可覆盖，便于定制

5. 错误处理

完善的异常捕获机制：

javascript

try {
  const data = await this.fetchSignatureData();
  if (!data) {
    console.error('数据加载失败，请稍后重试');
    return false;
  }
  this.fillTemplate(data);
  return true;
} catch (error) {
  console.error('初始化失败:', error);
  return false;
}

Babel

手写一个简易编译器

Babel本质上就是一个编译器。把一种代码变成另一种代码。
我们将要实现一个最简单的Babel核心功能：将ES6的箭头函数转换为ES5的普通函数。
我们不要去背那些复杂的概念，编译器的工作流程在任何语言里都是一样的，只有三个阶段：

1. 解析(Parse)：把代码字符串变成树结构(AST)。
2. 转换(Transform)：在树上修修补补，把“箭头函数节点”改成“普通函数节点”。
3. 生成(Generate)：把改好的树重新变回代码字符串。

一、为什么需要将代码解析为 AST

我们先看一个简单的代码：

const add = (a, b) => a + b;

如果不生成AST，直接用正则替换，你可能会写出 code.replace('=>', 'function')。 但如果代码是这样的：

const str = "这个箭头 => 是字符串不是代码";
const func = () => { return "=>"; };

正则就不管用了。它分不清哪个是语法，哪个是字符串内容。
只有通过某种方式把代码拆解成 树状结构 去进行表示，我们才能精准地知道每行代码的实际含义，比如这是一个变量声明，那是一个函数表达式。
这里我们使用 @babel/parser 来生成AST（因为手写词法分析器和语法分析器通过大量switch-case处理字符，逻辑虽简单但代码量太大，这里我们聚焦于核心的转换逻辑）。

二、AST长什么样

我们先看看上面那句 const add = (a, b) => a + b; 解析出来是什么东西。

{
  "type": "VariableDeclaration", // 变量声明
  "kind": "const",
  "declarations": [
    {
      "type": "VariableDeclarator",
      "id": { "type": "Identifier", "name": "add" },
      "init": {
        "type": "ArrowFunctionExpression", // 重点在这里：箭头函数表达式
        "params": [
          { "type": "Identifier", "name": "a" },
          { "type": "Identifier", "name": "b" }
        ],
        "body": {
          "type": "BinaryExpression", // 二进制表达式 (a + b)
          "left": { "type": "Identifier", "name": "a" },
          "operator": "+",
          "right": { "type": "Identifier", "name": "b" }
        }
      }
    }
  ]
}

转换的目标很明确：找到 ArrowFunctionExpression 类型的节点，把它替换成 FunctionExpression 类型的节点，同时处理一下函数体。

三、实现核心：遍历器(Traverser)

Babel最核心的部分不是解析，而是如何遍历这棵树。我们需要写一个函数，它能递归地访问树的每一个节点。当它遇到我们需要处理的节点时，调用我们提供的插件方法。 这是一个最基础的遍历器实现：

function traverse(ast, visitor) {
  // 遍历数组类型的属性（比如 body 里的多行代码）
  function traverseArray(array, parent) {
    array.forEach(child => traverseNode(child, parent));
  }

  // 遍历单个节点
  function traverseNode(node, parent) {
    if (!node || typeof node !== 'object') return;

    // 1. 如果visitor里定义了当前节点类型的处理函数，就执行它
    // 比如 visitor.ArrowFunctionExpression(node, parent)
    const method = visitor[node.type];
    if (method) {
      method(node, parent);
    }

    // 2. 递归遍历当前节点的所有属性
    // 比如遍历 body, params, left, right 等属性
    Object.keys(node).forEach(key => {
      const child = node[key];
      if (Array.isArray(child)) {
        traverseArray(child, node);
      } else {
        traverseNode(child, node);
      }
    });
  }

  traverseNode(ast, null);
}

这段代码的逻辑是：从根节点开始，先检查有没有对应的插件函数要执行，执行完后，继续递归找它的子节点。只要树没走完，就一直递归下去。

四、实现插件：转换箭头函数

现在我们有了遍历器，就可以写“插件”了。插件就是定义由于怎么修改节点。 我们要把箭头函数：

(a, b) => a + b

变成普通函数：

function(a, b) { return a + b; }

转换逻辑的具体步骤：

1. 找到 ArrowFunctionExpression 节点。
2. 保留它的 params (参数)。
3. 处理 body。箭头函数如果直接返回表达式（没有花括号），变成普通函数时需要加 { return ... }。
4. 把节点类型改为 FunctionExpression。

const transformer = {
  ArrowFunctionExpression(node) {
    // 1. 修改节点类型
    node.type = 'FunctionExpression';
    
    // 2. 处理函数体
    // 如果原体不是块语句（比如是 x => x + 1 这种直接返回的）
    // 我们需要把它包装成 { return x + 1; }
    if (node.body.type !== 'BlockStatement') {
      node.body = {
        type: 'BlockStatement',
        body: [{
          type: 'ReturnStatement',
          argument: node.body
        }]
      };
    }
    
    // 普通函数通常不需要 generator 或 async 属性，除非原样保留
    node.expression = false; 
  }
};

这里我们直接修改了 node 对象。因为AST本质上就是对象引用，直接修改树上的属性，整棵树的结构就变了。

五、代码生成(Generator)

树修改完了，最后一步是把树变回字符串。 这一步通常很繁琐，因为要处理缩进、括号、分号。为了演示核心逻辑，我们手写一个极简版的生成器，只处理我们涉及到的几种节点。

function generate(node) {
  switch (node.type) {
    case 'Program':
      return node.body.map(generate).join('\n');
      
    case 'VariableDeclaration':
      return `${node.kind} ${node.declarations.map(generate).join(', ')};`;
      
    case 'VariableDeclarator':
      return `${generate(node.id)} = ${generate(node.init)}`;
      
    case 'Identifier':
      return node.name;
      
    case 'FunctionExpression':
      // 组装函数字符串：function(参数) { 函数体 }
      const params = node.params.map(generate).join(', ');
      const body = generate(node.body);
      return `function(${params}) ${body}`;
      
    case 'BlockStatement':
      return `{\n${node.body.map(generate).join('\n')}\n}`;
      
    case 'ReturnStatement':
      return `return ${generate(node.argument)};`;
      
    case 'BinaryExpression':
      return `${generate(node.left)} ${node.operator} ${generate(node.right)}`;
      
    default:
      throw new Error(`Unknown node type: ${node.type}`);
  }
}

生成器逻辑：递归地拼接字符串。遇到 BinaryExpression 就拼左右两边，遇到 FunctionExpression 就拼关键字和参数。

六、串联整个流程(Compiler)

最后，我们把解析、转换、生成串起来，就是一个迷你版的 Babel。

const parser = require('@babel/parser'); // 借用parser，专注转换逻辑

function myBabelCompiler(code) {
  // 1. 解析 (Code -> AST)
  const ast = parser.parse(code);

  // 2. 转换 (AST -> New AST)
  // 传入我们的访问器对象
  traverse(ast, transformer);

  // 3. 生成 (New AST -> New Code)
  const output = generate(ast);

  return output;
}

// 测试
const sourceCode = "const add = (a, b) => a + b;";
const targetCode = myBabelCompiler(sourceCode);

console.log(targetCode);
// 输出结果:
// const add = function(a, b) {
// return a + b;
// };

总结

实现一个Babel，不要把问题想得太复杂，其实就是三个步骤：

1. 对象化：代码是字符串，没法改，先变成对象（AST）。
2. 递归：对象嵌套太深，必须用递归函数（Visitor）去一层层找。
3. 还原：改完对象属性后，按照语法规则把字符串拼回去。 真正的Babel虽然庞大，因为它要处理几百种语法节点，还要处理作用域(Scope)和引用关系，但核心骨架就是上面这几十行代码。当你写Babel插件时，你其实就是在写那个 transformer 对象里的函数。

Babel工程化配置与使用

刚才我们手写了一个微型编译器，搞懂了原理。但在实际工作中，我们不可能自己去写AST遍历器和生成器。我们直接使用Babel官方提供的工具链。

这里有一个非常反直觉的事实：Babel本身什么都不做。

如果你只安装 @babel/core 然后运行它，你把 ES6 代码丢进去，出来的还是 ES6 代码。它只是把代码解析成AST，然后又打印出来，中间没有任何修改。它不知道你要干什么。

要让它干活，必须明确告诉它：我要转换箭头函数，或者我要转换类(Class)。这些具体的转换功能，就是 Plugin（插件）；而为了方便，把一堆常用的插件打包在一起，就是 Preset（预设）。

一、基础配置：从零开始搭建

我们不讲虚的，直接看在一个空文件夹里怎么把 Babel 跑起来。

1. 初始化项目与安装核心库

你需要安装三个最基础的包：

• @babel/core: 编译器核心，负责解析和生成。
• @babel/cli: 命令行工具，让我们能在终端里运行 babel 命令。
• @babel/preset-env: 这是一个智能预设，包含了所有现代 JS 语法的转换插件。

npm init -y
npm install --save-dev @babel/core @babel/cli @babel/preset-env

2. 编写配置文件

在项目根目录创建一个 babel.config.json 文件。这是控制 Babel 行为的大脑。最简单的配置只需要一行：告诉 Babel 使用 preset-env。

{
  "presets": ["@babel/preset-env"]
}

3. 运行测试

创建一个 src/index.js，写点 ES6 代码：

const sayHello = () => console.log("Hello");

在终端运行编译命令：

npx babel src --out-dir dist

打开生成的 dist/index.js，你会发现箭头函数变成了 function，const 变成了 var。这就是 preset-env 在起作用。它默认把所有新语法都转成了 ES5。

二、按需编译：Targets 的重要性

上面的默认配置有一个大问题：它太“笨”了。

它把所有代码都转成了 ES5，哪怕你只是跑在最新的 Chrome 浏览器上。现代浏览器原生支持 const 和箭头函数，强行转换只会让代码体积变大，运行变慢。

我们需要告诉 Babel 我们的代码要在什么环境下运行。

修改 babel.config.json：

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "chrome": "88",
          "ie": "11"
        }
      }
    ]
  ]
}

这里我们配置了 targets。 如果你把 ie: "11" 去掉，只保留 chrome: "88"，再次编译，你会发现 const 和箭头函数被保留了，没有被转换。

这是因为 Babel 查表发现 Chrome 88 原生支持这些语法，所以它直接跳过了转换步骤。这是 Babel 配置中最核心的优化点：只转换目标环境不支持的语法。

三、处理API：Polyfill (垫片)

这是新手最容易混淆的地方。Babel 有两类转换：

1. 语法转换 (Syntax Transform)：比如 => 转成 function，class 转成 prototype。这是 preset-env 擅长的。
2. API 添加 (Polyfill)：比如 Array.from，new Promise()，Map。

如果你在代码里写 new Promise()，Babel 默认是不处理的。因为从语法角度看，这就是创建了一个对象，语法没问题。但在 IE11 里运行会直接报错 Promise is not defined。

我们需要引入 core-js 来实现这些缺少的 API。

不要全量引入，那样包会很大。我们要配置 Babel 自动按需引入。

首先安装 core-js：

npm install core-js

修改 babel.config.json，开启 useBuiltIns: "usage"：

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "chrome": "58",
          "ie": "11"
        },
        "useBuiltIns": "usage", // 关键配置：按需引入
        "corejs": 3             // 指定 core-js 版本
      }
    ]
  ]
}

现在，如果在你的代码里写了 new Promise()，Babel 编译时会自动在文件头部加上一句： require("core-js/modules/es.promise.js")。

如果你没用到 Promise，它就不加。这就是 usage 模式的威力。

四、在 Webpack 中集成

在实际开发中，我们很少直接运行 npx babel。通常是配合 Webpack 打包时自动转换。这需要用到 babel-loader。

这是 Webpack 和 Babel 的连接桥梁。Webpack 负责读取文件，发现是 .js 后，交给 babel-loader，babel-loader 调用 @babel/core 进行转换，转换完把代码还给 Webpack。

webpack.config.js 配置示例：

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/, // 极其重要：千万别编译 node_modules，慢且容易出错
        use: {
          loader: 'babel-loader',
          // options 可以在这里写，也可以直接读取 babel.config.json
          // 推荐使用独立配置文件，更清晰
        }
      }
    ]
  }
};

只要项目根目录下有 babel.config.json，babel-loader 会自动读取它，不需要重复配置。

总结 Babel 使用的核心逻辑

1. Babel 核心只是空壳，必须通过配置文件告诉它用什么插件。
2. Preset-env 是万能钥匙，它根据 targets 决定要转换哪些语法，避免过度编译。
3. 语法 != API。=> 是语法，Promise 是 API。处理 API 需要配置 core-js 和 useBuiltIns: "usage"。
4. exclude node_modules。在使用 Webpack 时，永远记得排除 node_modules，第三方包通常已经是编译好的，重复编译纯属浪费时间。

手写 Babel 插件：复刻 babel-plugin-import

我们要写一个真的能用的、在生产环境中极其常见的插件。

很多 UI 组件库（比如 Ant Design）或者工具库（比如 Lodash），都有一个痛点：文件太大。

当你写下这行代码时：

import { Button, Alert } from 'antd';

在没有优化的情况下，Webpack 会把整个 antd 库（几百个组件）全打包进去，哪怕你只用了两个组件。我们要写的插件，就是要把上面那一行代码，在编译时自动转换成：

import Button from 'antd/lib/button';
import Alert from 'antd/lib/alert';

这样就能按需加载，体积瞬间变小。这个插件逻辑非常经典，涉及了节点查找、节点替换、多节点生成这几个 Babel 插件最核心的操作。

一、准备工作

写插件的第一步永远不是写代码，而是对比 AST。我们要搞清楚，处理前的 AST 长什么样，处理后长什么样。

处理前 (import { Button } from 'antd')： 它是一个 ImportDeclaration 节点。

• source: 值是 'antd'。
• specifiers: 这是一个数组。里面有一个 ImportSpecifier，它的 imported 属性是 Button（引入的名字），local 属性也是 Button（本地使用的名字）。

处理后 (import Button from 'antd/lib/button')： 变成了两个（或多个）ImportDeclaration 节点。

• 每个节点都是 ImportDefaultSpecifier（注意这里变成了默认导入，因为具体的组件文件通常是 export default）。
• source: 值变成了 'antd/lib/button'。

处理方案：

1. 监听：专门盯着 ImportDeclaration 类型的节点。
2. 检查：看它的来源库是不是我们要优化的库（比如 'antd'）。
3. 提取：如果是，就把里面的 Button、Alert 这些名字取出来。
4. 构造：用这些名字生成新的 import 语句。
5. 替换：用新生成的数组，替换掉原来那一个老节点。

二、开始编写插件代码

创建一个 my-import-plugin.js 文件。

Babel 插件的标准写法是一个函数，它接受一个 babel 对象作为参数。我们需要从这个对象里拿出 types，这是 Babel 提供的节点构造工厂。你可以把它想象成乐高积木的模具，用来生成新的 AST 节点。

module.exports = function(babel) {
  const { types: t } = babel; // 这是我们的工厂

  return {
    visitor: {
      // 我们只关心 import 语句
      ImportDeclaration(path, state) {
        const { node } = path;

        // 1. 检查：如果引入的库不是 'antd'，直接跳过，不做处理
        // state.opts 是我们在配置文件里传给插件的参数
        // 这样插件就不仅仅能处理 antd，也能处理 lodash 等其他库
        const libraryName = state.opts.libraryName || 'antd';
        if (node.source.value !== libraryName) {
          return;
        }

        // 2. 检查：如果是默认导入 (import Antd from 'antd')，不仅没法按需加载，还说明用户可能真想引入全量
        // 我们只处理 { Button } 这种命名导入 (ImportSpecifier)
        if (!t.isImportSpecifier(node.specifiers[0])) {
          return;
        }

        // 3. 核心逻辑：遍历原来的 specifiers，生成新的 import 节点数组
        const newImports = node.specifiers.map(specifier => {
          // specifier.imported.name 是 "Button"
          // specifier.local.name 是我们代码里用的变量名 (通常也是 "Button")
          const componentName = specifier.imported.name;
          const localName = specifier.local.name;

          // 构造新的路径: 'antd/lib/button'
          // 这里简单的转成小写，实际工程中可能需要驼峰转连字符
          const newPath = `${libraryName}/lib/${componentName.toLowerCase()}`;

          // 使用 Babel 的 types 工具创建新节点
          // 生成: import localName from 'newPath'
          return t.importDeclaration(
            [t.importDefaultSpecifier(t.identifier(localName))],
            t.stringLiteral(newPath)
          );
        });

        // 4. 替换：用新的节点数组替换原来的一个节点
        // replaceWithMultiple 专门用来把一个节点变成一堆节点
        path.replaceWithMultiple(newImports);
      }
    }
  };
};

这段代码虽然短，但它展示了 Babel 插件最核心的逻辑：Path（路径）操作。 path 对象非常强大，它不只是当前节点，还包含了父节点、兄弟节点的信息，以及最重要的操作方法（比如 replaceWithMultiple, remove, insertBefore）。

三、调试与运行

插件写好了，怎么用呢？我们不需要把它发布到 npm，直接在本地引用测试。

在项目根目录下创建一个 .babelrc 或者 babel.config.json，配置上我们刚写的插件：

{
  "presets": ["@babel/preset-env"],
  "plugins": [
    [
      "./my-import-plugin.js", 
      {
        "libraryName": "antd" 
      }
    ]
  ]
}

这里我们用了相对路径 ./my-import-plugin.js，并且传入了参数 libraryName: "antd"。

验证效果

创建一个 test.js：

import { Button, Modal } from 'antd';
console.log(Button, Modal);

然后运行 Babel 编译（假设你已经安装了 @babel/cli）：

npx babel test.js

你的控制台输出应该会变成这样：

import Button from "antd/lib/button";
import Modal from "antd/lib/modal";
console.log(Button, Modal);

四、进阶思考：为什么说这有难度？

刚才的代码是一个“乞丐版”实现。在真实场景中，情况会复杂得多，这也是为什么 babel-plugin-import 源码有几百行的原因。

1. 样式的处理 真正的按需加载，不仅仅是加载 JS，还要加载对应的 CSS。 你需要不仅生成 import Button from ...，还要顺便生成 import 'antd/lib/button/style/css'。这需要在 map 循环里多生成一个 importDeclaration 节点。

2. 作用域冲突 如果你在代码里已经定义了一个叫 Button 的变量，然后再 import { Button } from 'antd'，Babel 插件如果不小心处理，可能会导致变量名冲突。虽然在这个场景下概率不大，但写通用插件时，通常需要用 path.scope.generateUidIdentifier 来生成唯一的变量名。

3. 路径转换规则 我们只用了简单的 .toLowerCase()。但有的组件叫 DatePicker，文件路径可能是 date-picker。这时候就需要引入更复杂的命名转换算法（Kebab Case）。

总结

写好一个 Babel 插件，其实就是三个步骤的循环：

1. 看 AST：用 AST Explorer 这种在线工具，把你的源代码放进去，看它是怎么被解析的。
2. 造节点：利用 babel.types (t) 构建你想要的新结构。
3. 换节点：利用 path 提供的 API，把旧的换成新的。

当你掌握了 visitor 模式和 types 构建器，你就掌握了修改 JavaScript 语言本身的权力。

Wepack实现

webpack打包功能实现

webpack打包与模块加载原理(从JS入口文件出发如何进行简单打包 -> __webpack_require__具体实现 -> 一个最基础的bundle.js至少具备的内容 -> 实现一个基本的webpack打包功能)

一、从JS文件打包说起

1.1 基本打包过程

当我们有以下文件结构时：

src/
  ├── a.js (入口文件)
  └── b.js (依赖文件)

a.js (入口文件)：

import { getValue } from './b.js';
console.log(getValue());

b.js (依赖文件)：

export function getValue() {
  return 'Hello from b.js';
}

1.2 打包后的结果(自测：请说出打包后的代码形式)

以a.js为入口进行打包后，生成的bundle.js会将每个模块包装成函数形式：

// 简化版的打包结果
{
  "./src/a.js": function(module, exports, __webpack_require__) {
    eval(`
      const { getValue } = __webpack_require__("./src/b.js");
      console.log(getValue());
    `);
  },
  "./src/b.js": function(module, exports, __webpack_require__) {
    eval(`
      function getValue() {
        return 'Hello from b.js';
      }
      exports.getValue = getValue;
    `);
  }
}

关键变化：

• 原本的 import { getValue } from './b.js' 被转换为 __webpack_require__("./src/b.js")
• 每个模块被包装在函数中，接收 module, exports, __webpack_require__ 参数

二、webpack_require 的实现原理(自测：说出核心代码实现)

2.1 函数签名与作用

function __webpack_require__(moduleId) {
  // 参数：moduleId - 模块的路径标识符（如 "./src/b.js"）
  // 返回值：该模块的所有导出内容（exports对象）
}

2.2 完整实现过程

// 模块缓存对象
var __webpack_module_cache__ = {};

// 主要的模块加载函数
function __webpack_require__(moduleId) {
  // 1. 检查缓存，避免重复加载
  var cachedModule = __webpack_module_cache__[moduleId];
  if (cachedModule !== undefined) {
    return cachedModule.exports;
  }
  
  // 2. 创建新的模块对象并缓存
  var module = __webpack_module_cache__[moduleId] = {
    exports: {}
  };
  
  // 3. 执行模块函数，填充exports
  __webpack_modules__[moduleId](module, module.exports, __webpack_require__);
  
  // 4. 返回模块的导出内容
  return module.exports;
}

2.3 模块执行机制

关键在于这一行：

__webpack_modules__[moduleId](module, module.exports, __webpack_require__);

执行过程：

1. 从 __webpack_modules__ 对象中获取对应的模块函数
2. 传入三个参数：module（模块对象）、module.exports（导出对象）、__webpack_require__（加载函数）
3. 模块函数内部通过修改 module.exports 来导出内容
4. 执行完成后返回填充好的 module.exports

三、Bundle.js的基本结构(自测：说出结构是什么以及为什么)

一个完整的bundle.js至少需要包含以下内容：

3.1 核心组件

// 1. 模块存储对象 - 存放所有模块函数
var __webpack_modules__ = {
  "./src/a.js": function(module, exports, __webpack_require__) { /* ... */ },
  "./src/b.js": function(module, exports, __webpack_require__) { /* ... */ }
};

// 2. 模块缓存对象
var __webpack_module_cache__ = {};

// 3. 模块加载函数
function __webpack_require__(moduleId) { /* ... */ }

// 4. 启动应用程序
__webpack_require__("./src/a.js");

3.2 完整示例

(function() {
  "use strict";
  
  var __webpack_modules__ = {
    "./src/a.js": function(module, exports, __webpack_require__) {
      eval(`
        const { getValue } = __webpack_require__("./src/b.js");
        console.log(getValue());
      `);
    },
    "./src/b.js": function(module, exports, __webpack_require__) {
      eval(`
        function getValue() {
          return 'Hello from b.js';
        }
        exports.getValue = getValue;
      `);
    }
  };
  
  var __webpack_module_cache__ = {};
  
  function __webpack_require__(moduleId) {
    var cachedModule = __webpack_module_cache__[moduleId];
    if (cachedModule !== undefined) {
      return cachedModule.exports;
    }
    
    var module = __webpack_module_cache__[moduleId] = {
      exports: {}
    };
    
    __webpack_modules__[moduleId](module, module.exports, __webpack_require__);
    
    return module.exports;
  }
  
  // 启动入口模块
  __webpack_require__("./src/a.js");
})();

总结

Webpack的核心打包原理：

1. 模块化处理：将每个文件包装成函数，统一模块接口，并存储在全局webpack——modules中。
2. 依赖管理：通过__webpack_require__实现模块间的加载和缓存，获取文件导出内容，并且缓存导出结果下次复用。
3. 代码整合：将所有模块函数和运行时代码组装成单一文件 bundle.js 用立即执行函数进行运行。

这种设计让浏览器能够执行原本不支持的ES6模块语法，同时实现了高效的模块缓存和按需加载机制。

实现Webpack依赖分析(自测：如何实现分析依赖，两种优缺点)

实现步骤

1. 依赖分析：从入口文件开始，递归找到所有依赖的文件
2. 代码转换：将每个文件转换为模块函数格式
3. 生成bundle：将所有模块函数组装成最终的bundle.js

依赖分析的两种方法

方法一：正则表达式

function findDependenciesByRegex(code) {
  const importRegex = /import\s+.*?\s+from\s+['"](.*?)['"];?/g;
  const dependencies = [];
  let match;
  
  while ((match = importRegex.exec(code)) !== null) {
    dependencies.push(match[1]);
  }
  
  return dependencies;
}

优点：

• 实现简单，代码量少
• 执行速度快

缺点：

• 容易误匹配字符串中的内容
• 无法处理复杂的import语法
• 不够准确和可靠

问题示例：

// 这种情况会被错误匹配
const code = `
  console.log("import something from 'fake-module'");
  import { real } from './real-module';
`;

方法二：抽象语法树（AST）

const babel = require('@babel/core');
const traverse = require('@babel/traverse').default;

function findDependenciesByAST(code) {
  const dependencies = [];
  
  // 将代码解析为AST
  const ast = babel.parse(code, {
    sourceType: 'module'
  });
  
  // 遍历AST节点找到import的路径
  traverse(ast, {
    ImportDeclaration(path) {
      dependencies.push(path.node.source.value);
    }
  });
  
  return dependencies;
}

优点：

• 精确解析，不会误匹配字符串
• 能处理各种复杂的import语法
• 提供完整的语法信息

缺点：

• 实现复杂度较高
• 需要引入额外的解析库
• 执行速度相对较慢

为什么AST更准确：

• AST将代码解析为树形结构，每个import语句会生成专门的ImportDeclaration节点
• 字符串内容不会被解析为import节点，从根本上避免了误匹配
• 能够准确识别import语句的各个组成部分（导入内容、来源路径等）

手写实现抽象语法树与完整模块打包工具

一、获取JS文件依赖信息，获取依赖文件绝对路径：如何将代码解析为抽象语法树(AST)

1.1 使用@babel/parser解析代码

抽象语法树（Abstract Syntax Tree, AST）是源代码的抽象语法结构的树状表示。我们可以使用 @babel/parser（原名 Babylon）将 JavaScript 代码字符串解析为 AST 对象。

const parser = require('@babel/parser');

const code = `import React from 'react';`;
const ast = parser.parse(code, {
  sourceType: 'module' // 指定代码为模块化代码
});

console.log(ast);

解析后的 AST 本质上是一个 JavaScript 对象，其中包含描述代码结构的各种节点。当打印 AST 时，某些嵌套较深的属性会以其类型（如 Node、Position）代替显示，但直接转换为字符串可以看到完整结构。

1.2 手动遍历AST获取依赖

AST 的 program.body 属性是一个数组，包含了当前文件的所有顶级语句。我们可以遍历这个数组，找到所有类型为 ImportDeclaration 的节点，然后从中提取导入路径。

const dependencies = [];
ast.program.body.forEach(node => {
  if (node.type === 'ImportDeclaration') {
    dependencies.push(node.source.value);
  }
});

console.log(dependencies); // ['react']

这种方法虽然可行，但手动遍历 AST 结构繁琐且容易出错。

1.3 使用@babel/traverse简化遍历

@babel/traverse 提供了一个更便捷的方式来遍历 AST。我们可以使用它来查找特定类型的节点。

const traverse = require('@babel/traverse').default;

const dependencies = [];
traverse(ast, {
  ImportDeclaration(path) {
    dependencies.push(path.node.source.value);
  }
});

console.log(dependencies); // ['react']

这种方法更加简洁和可靠，我们只需要定义对特定节点类型的处理函数即可。

二、如何实现从入口文件开始自动化依赖分析所有依赖文件

2.1 单文件依赖分析

我们可以封装一个函数来分析单个文件的依赖：

const fs = require('fs');
const path = require('path');

function getDependencies(filename) {
  const content = fs.readFileSync(filename, 'utf-8');
  const ast = parser.parse(content, { sourceType: 'module' });

  const dependencies = [];
  traverse(ast, {
    ImportDeclaration(path) {
      const importPath = path.node.source.value;
      // 将相对路径转换为绝对路径
      const absolutePath = path.resolve(path.dirname(filename), importPath);
      dependencies.push(absolutePath);
    }
  });

  return {
    filename,
    dependencies
  };
}

2.2 广度优先搜索分析所有依赖

从入口文件开始，我们可以使用广度优先搜索（BFS）来分析整个项目的所有依赖：

function analyzeDependencies(entryFile) {
  const queue = [entryFile];
  const allDependencies = new Set();
  const dependencyGraph = new Map();

  while (queue.length > 0) {
    const currentFile = queue.shift();

    if (allDependencies.has(currentFile)) continue;
    allDependencies.add(currentFile);

    const { dependencies } = getDependencies(currentFile);
    dependencyGraph.set(currentFile, dependencies);

    dependencies.forEach(dep => {
      if (!allDependencies.has(dep)) {
        queue.push(dep);
      }
    });
  }

  return dependencyGraph;
}

这样我们就得到了一个包含所有模块及其依赖关系的映射表。

三、ES模块语法转换为CommonJS形式

为了使模块代码能在打包环境中运行，我们需要将 ES 模块语法转换为 CommonJS 形式。这包括处理 import 和 export 语句。

3.1 ImportDeclaration转换

对于不同类型的 import 语法，我们进行不同的转换：

const { transformFromAst } = require('@babel/core');
const t = require('@babel/types');

function transformImportDeclaration(ast, moduleIdMap) {
  traverse(ast, {
    ImportDeclaration(path) {
      const source = path.node.source.value;
      const absolutePath = path.resolve(path.dirname(path.hub.file.opts.filename), source);

      // 生成模块ID
      const moduleId = moduleIdMap.get(absolutePath) || generateModuleId(absolutePath);
      moduleIdMap.set(absolutePath, moduleId);

      const specifiers = path.node.specifiers;
      const imports = specifiers.map(spec => {
        if (t.isImportDefaultSpecifier(spec)) {
          // 默认导入：import foo from 'module' → const foo = webpack_require(moduleId)
          return t.variableDeclarator(
            t.identifier(spec.local.name),
            t.callExpression(t.identifier('webpack_require'), [t.numericLiteral(moduleId)])
          );
        } else if (t.isImportSpecifier(spec)) {
          // 命名导入：import { foo } from 'module' → const foo = webpack_require(moduleId).foo
          return t.variableDeclarator(
            t.identifier(spec.local.name),
            t.memberExpression(
              t.callExpression(t.identifier('webpack_require'), [t.numericLiteral(moduleId)]),
              t.identifier(spec.imported.name)
            )
          );
        }
      }).filter(Boolean);

      // 替换 import 语句为 const 声明
      path.replaceWith(t.variableDeclaration('const', imports));
    }
  });
}

3.2 ExportDefaultDeclaration转换

将 export default 语句转换为 CommonJS 形式：

function transformExportDefaultDeclaration(ast) {
  traverse(ast, {
    ExportDefaultDeclaration(path) {
      // 替换 export default foo 为 module.exports = foo
      path.replaceWith(
        t.expressionStatement(
          t.assignmentExpression(
            '=',
            t.memberExpression(t.identifier('module'), t.identifier('exports')),
            path.node.declaration
          )
        )
      );
    }
  });
}

3.3 ExportNamedDeclaration转换

将命名导出语句转换为 CommonJS 形式：

function transformExportNamedDeclaration(ast) {
  traverse(ast, {
    ExportNamedDeclaration(path) {
      // 替换 export { foo } 为 module.exports.foo = foo
      if (path.node.specifiers.length) {
        const exports = path.node.specifiers.map(spec => {
          return t.expressionStatement(
            t.assignmentExpression(
              '=',
              t.memberExpression(
                t.memberExpression(t.identifier('module'), t.identifier('exports')),
                t.identifier(spec.exported.name)
              ),
              t.identifier(spec.local.name)
            )
          );
        });
        path.replaceWithMultiple(exports);
      }
    }
  });
}

3.4 模块ID生成

我们使用一个简单的自增 ID 来标识每个模块：

const moduleIdMap = new Map();
let nextModuleId = 0;

function generateModuleId(modulePath) {
  if (!moduleIdMap.has(modulePath)) {
    moduleIdMap.set(modulePath, nextModuleId++);
  }
  return moduleIdMap.get(modulePath);
}

实际 Webpack 会使用更复杂的哈希算法生成模块 ID，以实现更好的缓存效果。

四、打包产物(bundle.js)工作原理，核心概念和结构

4.1 模块打包的核心概念

打包工具的核心功能包括：

• 模块作用域隔离：通过函数作用域将每个模块封装
• 模块导入导出：实现模块间的引用关系
• 模块缓存：避免重复执行模块代码
• 入口执行：从入口文件开始执行整个应用

4.2 简化版打包产物结构

一个简化版的打包产物（bundle.js）通常包含以下部分：

(function(modules) {
  // 模块缓存
  const installedModules = {};

  // 模拟webpack_require函数
  function webpack_require(moduleId) {
    // 检查缓存
    if (installedModules[moduleId]) {
      return installedModules[moduleId].exports;
    }

    // 创建新模块
    const module = installedModules[moduleId] = {
      exports: {}
    };

    // 执行模块函数
    modules[moduleId].call(
      module.exports,
      module,
      module.exports,
      webpack_require
    );

    return module.exports;
  }

  // 执行入口模块
  return webpack_require('<%= entryModuleId %>');
})({
  <% modules.forEach((module) => { %>
    '<%= module.id %>': function(module, exports, webpack_require) {
        <%= module.code %>
     },
  <% }); %>
});

注意：这里使用的是 webpack_require 而不是 require，以避免与 Node.js 的原生 require 混淆，他们不是一个函数

五、使用EJS动态生成打包产物

5.1 EJS模板基础

EJS 是一个简单的模板引擎，可以让我们用 JavaScript 生成 HTML 或其他文本格式。基本语法：

• <%= variable %>：输出变量值
• <% code %>：执行 JavaScript 代码

5.2 创建打包模板

我们可以创建一个 EJS 模板来动态生成打包产物：

const ejs = require('ejs');

const template = `
(function(modules) {
  const installedModules = {};

  function webpack_require(moduleId) {
    if (installedModules[moduleId]) {
      return installedModules[moduleId].exports;
    }

    const module = installedModules[moduleId] = {
      exports: {}
    };

    modules[moduleId].call(
      module.exports,
      module,
      module.exports,
      webpack_require
    );

    return module.exports;
  }

  return webpack_require(<%= entryModuleId %>);
})({
  <% modules.forEach((module) => { %>
    <%= module.id %>: function(module, exports, webpack_require) {
      <%= module.code %>
    },
  <% }); %>
});
`;

5.3 渲染打包产物

使用 EJS 渲染模板并生成最终的打包文件：

function generateBundle(modules, entryId) {
  const moduleList = Array.from(modules.values()).map(mod => ({
    id: mod.id,
    code: mod.code
  }));

  const bundleCode = ejs.render(template, {
    entryModuleId: entryId,
    modules: moduleList
  });

  return bundleCode;
}

六、完整的打包流程实现

整合所有步骤，实现完整的打包流程：

const fs = require('fs');
const path = require('path');
const parser = require('@babel/parser');
const traverse = require('@babel/traverse').default;
const generate = require('@babel/generator').default;
const t = require('@babel/types');

// 模块 ID 映射表
const moduleIdMap = new Map();
let nextModuleId = 0;

// 生成模块 ID
function generateModuleId(modulePath) {
  if (!moduleIdMap.has(modulePath)) {
    moduleIdMap.set(modulePath, nextModuleId++);
  }
  return moduleIdMap.get(modulePath);
}

// 解析模块内容，提取依赖并转换代码
function parseModule(modulePath) {
  const filename = path.resolve(modulePath);
  const content = fs.readFileSync(filename, 'utf-8');

  // 解析 AST
  const ast = parser.parse(content, {
    sourceType: 'module',
  });

  const dependencies = [];

  // 遍历 AST，提取 import 依赖并转换为 webpack_require
  traverse(ast, {
    ImportDeclaration(p) {
      const source = p.node.source.value;
      const absolutePath = path.resolve(path.dirname(filename), source);

      // 记录依赖
      dependencies.push(absolutePath);

      // 生成模块 ID
      const moduleId = generateModuleId(absolutePath);

      // 替换 import 语句为 webpack_require
      const specifiers = p.node.specifiers;
      const imports = specifiers.map(spec => {
        if (t.isImportDefaultSpecifier(spec)) {
          // 默认导入：import foo from 'module' → const foo = webpack_require(moduleId)
          return t.variableDeclarator(
            t.identifier(spec.local.name),
            t.callExpression(t.identifier('webpack_require'), [t.numericLiteral(moduleId)])
          );
        } else if (t.isImportSpecifier(spec)) {
          // 命名导入：import { foo } from 'module' → const foo = webpack_require(moduleId).foo
          return t.variableDeclarator(
            t.identifier(spec.local.name),
            t.memberExpression(
              t.callExpression(t.identifier('webpack_require'), [t.numericLiteral(moduleId)]),
              t.identifier(spec.imported.name)
            )
          );
        }
      }).filter(Boolean);

      // 替换 import 语句为 const 声明
      p.replaceWith(t.variableDeclaration('const', imports));
    },

    ExportDefaultDeclaration(p) {
      // 替换 export default 为 module.exports
      p.replaceWith(
        t.expressionStatement(
          t.assignmentExpression(
            '=',
            t.memberExpression(t.identifier('module'), t.identifier('exports')),
            p.node.declaration
          )
        )
      );
    },

    ExportNamedDeclaration(p) {
      // 替换 export { foo } 为 module.exports.foo = foo
      if (p.node.specifiers.length) {
        const exports = p.node.specifiers.map(spec => {
          return t.expressionStatement(
            t.assignmentExpression(
              '=',
              t.memberExpression(
                t.memberExpression(t.identifier('module'), t.identifier('exports')),
                t.identifier(spec.exported.name)
              ),
              t.identifier(spec.local.name)
            )
          );
        });
        p.replaceWithMultiple(exports);
      }
    },
  });

  // 生成转换后的代码
  const { code } = generate(ast);

  return {
    id: generateModuleId(filename),
    filename,
    dependencies,
    code,
  };
}

// 递归分析所有依赖
function analyzeDependencies(entry) {
  const entryModule = parseModule(entry);
  const queue = [entryModule];
  const modules = new Map();

  modules.set(entryModule.id, entryModule);

  while (queue.length > 0) {
    const currentModule = queue.shift();

    currentModule.dependencies.forEach(depPath => {
      const depModule = parseModule(depPath);

      if (!modules.has(depModule.id)) {
        modules.set(depModule.id, depModule);
        queue.push(depModule);
      }
    });
  }

  return modules;
}

// 生成打包后的代码
function generateBundle(modules, entryId) {
  const moduleList = Array.from(modules.values()).map(mod => `
  ${mod.id}: function(module, exports, webpack_require) {
    ${mod.code}
  },
`).join('\n');

  return `
(function(modules) {
  const installedModules = {};

  function webpack_require(moduleId) {
    if (installedModules[moduleId]) {
      return installedModules[moduleId].exports;
    }

    const module = installedModules[moduleId] = {
      exports: {}
    };

    modules[moduleId].call(
      module.exports,
      module,
      webpack_require
    );

    return module.exports;
  }

  return webpack_require(${entryId});
})({
${moduleList}
});
`;
}

// 主打包函数
function bundle(entryFile, outputFile) {
  const modules = analyzeDependencies(entryFile);
  const entryModule = Array.from(modules.values()).find(mod => mod.filename === path.resolve(entryFile));
  const bundleCode = generateBundle(modules, entryModule.id);

  fs.writeFileSync(outputFile, bundleCode);
  console.log(`✅ 打包完成: ${outputFile}`);
}

// 使用示例
bundle('./src/index.js', './dist/bundle.js');

七、总结

通过以上步骤，我们实现了一个简化版的模块打包工具，核心流程包括：

1. 使用 @babel/parser 将代码解析为 AST
2. 使用 @babel/traverse 遍历 AST 提取依赖关系
3. 将 ES 模块语法转换为 CommonJS 形式

• • 处理默认导入：import foo from 'module' → const foo = webpack_require(moduleId)
  • 处理命名导入：import { foo } from 'module' → const foo = webpack_require(moduleId).foo
  • 处理默认导出：export default foo → module.exports = foo
  • 处理命名导出：export { foo } → module.exports.foo = foo

4. 通过广度优先搜索分析整个项目的依赖图
5. 使用模块 ID 优化和代码转换完善打包产物
6. 动态生成最终的打包代码

Webpack Loader实现

一、Loader的基本概念

1.1 什么是Loader

Loader是Webpack的核心功能之一，它的作用是将非JavaScript文件转换为JavaScript模块，使得Webpack能够处理除了JS之外的各种类型的文件。

1.2 为什么需要Loader

原生Webpack的局限性

• Webpack原生只能理解JavaScript和JSON文件
• 当遇到其他格式文件时，需要转换为JavaScript语法才能被解析为AST(进行依赖分析也就是寻找import的子文件路径)

问题示例

// 以下代码会导致解析失败
import './styles.css';        // CSS文件不符合JS语法
import data from './data.json'; // JSON需要特殊处理

解析失败的原因：

• CSS文件内容如 .button { color: red; } 不符合JavaScript语法规范
• 直接解析会在AST生成阶段报错
• 需要先转换为有效的JavaScript导出语句

1.3 Loader的工作原理

Loader本质上是一个转换函数，它接收源文件内容，返回转换后的JavaScript代码：

// Loader的基本结构
module.exports = function(source) {
  // source: 原始文件内容字符串
  // 返回: 转换后的JavaScript代码字符串
  return `export default ${JSON.stringify(source)}`;
};

二、Loader的配置与执行机制

2.1 Webpack配置中的Loader

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /.json$/,           // 正则匹配文件类型
        use: ['json-loader']       // 使用的loader数组
      },
      {
        test: /.css$/,
        use: ['style-loader', 'css-loader'] // 多个loader的执行顺序
      }
    ]
  }
};

2.2 Loader的执行顺序

关键特性：Loader从右到左（从后到前）执行

use: ['style-loader', 'css-loader']
// 执行顺序：
// 1. css-loader 处理 .css 文件
// 2. style-loader 处理 css-loader 的输出结果

执行流程图：

原始CSS文件 → css-loader → JavaScript字符串 → style-loader → 最终JavaScript模块

2.3 在打包器中集成Loader机制

修改文件分析逻辑

class SimpleWebpack {
  constructor(entry, output, config = {}) {
    this.entry = entry;
    this.output = output;
    this.loaders = config.module?.rules || []; // 获取loader配置
    // ... 其他属性
  }

  /**
   * 应用匹配的loaders处理文件内容
   */
  applyLoaders(filePath, source) {
    let transformedSource = source;

    // 遍历所有loader规则
    for (const rule of this.loaders) {
      // 检查文件是否匹配当前规则
      if (rule.test.test(filePath)) {
        // 从右到左执行loaders
        const loaders = Array.isArray(rule.use) ? [...rule.use].reverse() : [rule.use];
        
        for (const loaderName of loaders) {
          const loader = this.loadLoader(loaderName);
          transformedSource = loader(transformedSource);
        }
        break; // 匹配到规则后停止检查其他规则
      }
    }

    return transformedSource;
  }

  /**
   * 加载并返回loader函数
   */
  loadLoader(loaderName) {
    // 在实际应用中，这里会从node_modules加载loader
    // 为了演示，我们使用内置的loader映射
    const builtinLoaders = {
      'json-loader': this.jsonLoader,
      'css-loader': this.cssLoader,
      'style-loader': this.styleLoader
    };

    return builtinLoaders[loaderName] || ((source) => source);
  }

  /**
   * 修改后的文件分析方法
   */
  analyzeFile(filePath) {
    if (this.modules.has(filePath)) {
      return this.modules.get(filePath);
    }

    let sourceCode = fs.readFileSync(filePath, 'utf-8');
    
    // 关键步骤：在AST解析前应用loaders
    sourceCode = this.applyLoaders(filePath, sourceCode);
    
    // 现在sourceCode已经是有效的JavaScript代码，可以安全解析为AST
    const ast = parser.parse(sourceCode, {
      sourceType: 'module'
    });

    // ... 后续AST分析逻辑
  }
}

三、简单实现json-loader

3.1 JSON文件处理需求

// 原始JSON文件 data.json
{
  "name": "webpack-demo",
  "version": "1.0.0"
}

// 期望的转换结果（JavaScript模块）
export default {
  "name": "webpack-demo", 
  "version": "1.0.0"
};

3.2 json-loader实现

/**
 * JSON Loader实现
 * 将JSON文件内容转换为JavaScript默认导出
 */
function jsonLoader(source) {
  // 验证JSON格式
  try {
    JSON.parse(source);
  } catch (error) {
    throw new Error(`Invalid JSON file: ${error.message}`);
  }

  // 转换为JavaScript模块导出语法
  return `export default ${source};`;
}

3.3 使用示例

// webpack配置
{
  test: /.json$/,
  use: ['json-loader']
}

// 在JavaScript中使用
import config from './config.json';
console.log(config.name); // "webpack-demo"

四、手写实现简易style-loader与css-loader

4.1 CSS文件处理的挑战

CSS文件无法直接被JavaScript引擎执行，需要通过DOM操作将样式注入到页面中。

处理策略：

1. css-loader：读取CSS内容并返回字符串
2. style-loader：将CSS字符串通过DOM操作插入到页面

4.2 css-loader实现

/**
 * CSS Loader实现
 * 将CSS文件内容转换为JavaScript字符串导出
 */
function cssLoader(source) {
  // 简单版本：直接返回CSS内容作为字符串
  const cssString = JSON.stringify(source);
  return `export default ${cssString};`;
}

4.3 style-loader实现

/**
 * Style Loader实现  
 * 将CSS字符串通过DOM操作注入到页面中
 */
function styleLoader(source) {
  // 从css-loader的输出中提取CSS内容
  // css-loader输出格式：export default "css content here";
  
  return `
    // 从css-loader获取CSS内容
    ${source}
    
    // 创建并插入style标签的函数
    function insertCSS(css) {
      if (typeof document === 'undefined') return;
      
      const style = document.createElement('style');
      style.type = 'text/css';
      
      if (style.styleSheet) {
        // IE8及以下版本
        style.styleSheet.cssText = css;
      } else {
        // 现代浏览器
        style.innerHTML = css;
      }
      
      document.head.appendChild(style);
    }
    
    // 立即执行：将CSS插入页面
    insertCSS(__webpack_require__.default || __webpack_require__);
  `;
}

4.4 更完善的style-loader实现

function styleLoader(source) {
  return `
    ${source}
    
    (function() {
      // 获取CSS内容（来自css-loader的输出）
      const css = typeof exports === 'object' && exports.default || exports;
      
      if (typeof css === 'string') {
        // 创建style标签
        const style = document.createElement('style');
        style.type = 'text/css';
        
        // 添加CSS内容
        if (style.styleSheet) {
          style.styleSheet.cssText = css;
        } else {
          style.appendChild(document.createTextNode(css));
        }
        
        // 插入到head中
        document.head.appendChild(style);
        
        // 支持热更新时的样式移除
        if (module.hot) {
          module.hot.dispose(function() {
            document.head.removeChild(style);
          });
        }
      }
    })();
    
    // 导出空对象（CSS不需要导出内容）
    export default {};
  `;
}

4.5 CSS处理流程梳理

完整处理流程：

1. 遇到 import './styles.css'
2. 匹配到 test: /.css$/, use: ['style-loader', 'css-loader']
3. 执行顺序（右到左）：
   
   原始CSS文件内容:
   ".button { color: red; background: blue; }"
   
   ↓ css-loader处理
   
   "export default ".button { color: red; background: blue; }";"
   
   ↓ style-loader处理  
   
   "// 插入CSS到DOM的JavaScript代码
    const css = ".button { color: red; background: blue; }";
    const style = document.createElement('style');
    style.innerHTML = css;
    document.head.appendChild(style);
    export default {};"
    
4. 生成的JavaScript代码被webpack打包
5. 运行时执行，CSS被注入到页面中

五、总结与扩展

5.1 Loader机制的核心价值

1. 扩展性：让Webpack能够处理任意类型的文件
2. 模块化：每个Loader职责单一，可组合使用
3. 标准化：统一的接口规范，便于开发和维护

5.2 常见Loader类型

• 转译类：babel-loader, typescript-loader
• 样式类：css-loader, style-loader, sass-loader
• 文件类：file-loader, url-loader
• 代码检查：eslint-loader
• 模板类：html-loader, vue-loader

5.3 开发Loader的最佳实践

1. 单一职责：每个Loader只做一件事
2. 链式调用：设计时考虑与其他Loader的配合
3. 错误处理：提供清晰的错误信息
4. 性能优化：缓存计算结果，避免重复处理
5. 选项支持：通过loader-utils获取用户配置

5.4 实际应用场景

• 组件化开发：CSS Modules解决样式隔离问题
• 预处理器：Sass/Less编译为CSS
• 代码转换：ES6+转换为ES5兼容代码
• 资源优化：图片压缩、文件合并

Webpack热更新(HMR)原理与实现(自测：说出具体原理和实现流程)

一、HMR解决的具体问题

在没有HMR（Hot Module Replacement）时，修改代码后的开发体验如下：

全量刷新 (Live Reload) ：修改代码 -> Webpack重新打包 -> 浏览器自动刷新页面 (window.location.reload())。
问题： 重新打包所有资源并在浏览器重新加载以及状态丢失

HMR的效果：
修改代码 -> 浏览器不刷新 -> 仅替换修改的模块代码 -> 保持当前页面状态不变。

二、HMR核心流程拆解

HMR不是单一功能，而是Webpack编译器（服务端）与浏览器运行时（客户端）配合的结果。

涉及的四个核心角色

1. Webpack Compiler：负责监听文件，编译代码。
2. HMR Server (通常集成在webpack-dev-server中)：建立WebSocket连接，负责将更新通知推送到浏览器。
3. Bundle Server：提供文件访问服务（http://localhost:8080/bundle.js）。
4. HMR Runtime：注入到打包后的bundle.js中的一段JS代码，负责在浏览器端接收WebSocket消息，并执行代码替换。

完整更新流程

1. 监听：Webpack Compiler 监听到文件变化（如 style.css 或 math.js）。
2. 增量编译：Webpack 不会重新打包所有文件，而是生成两个补丁文件：

• Manifest (JSON) ：描述哪些模块变了，新的hash值是多少。
• Update Chunk (JS) ：包含被修改模块的具体代码。

3. 推送消息：HMR Server 通过 WebSocket 向浏览器发送消息：{"type": "hash", "data": "新的hash值"} 和 {"type": "ok"}。
4. 检查更新：浏览器端的 HMR Runtime 收到消息，对比上一次的 hash，发现有更新。
5. 请求补丁：Runtime 发起 AJAX 请求获取 Manifest，再通过 JSONP 请求获取 Update Chunk。
6. 代码替换：Runtime 执行新下载的代码，替换掉 __webpack_modules__ 中对应的旧函数。

三、手写简易HMR实现逻辑

这里不展示完整的Webpack源码，而是实现HMR最核心的通信与模块替换逻辑。

服务端：监听编译与WebSocket通知

在开发服务器启动时，需要注入WebSocket服务。

// server.js (模拟 webpack-dev-server)
const WebSocket = require('ws');
const webpack = require('webpack');
const config = require('./webpack.config.js');

const compiler = webpack(config);
const app = require('express')();
const server = require('http').createServer(app);

// 1. 启动 WebSocket 服务器
const wss = new WebSocket.Server({ server });

// 2. 监听 Webpack 编译完成钩子
compiler.hooks.done.tap('HMRPlugin', (stats) => {
  // 获取新生成的 hash
  const hash = stats.hash;
  
  // 3. 向所有连接的客户端广播消息
  wss.clients.forEach(client => {
    client.send(JSON.stringify({
      type: 'hash',
      data: hash
    }));
    client.send(JSON.stringify({
      type: 'ok'
    }));
  });
});

// 启动编译监视
compiler.watch({}, (err) => {
  console.log('Webpack is watching files...');
});

server.listen(8080);

客户端：Runtime代码注入

Webpack打包时，会将以下代码注入到 bundle.js 的入口处。

// bundle.js 中的注入代码 (简化版)

// 1. 建立连接
const socket = new WebSocket('ws://localhost:8080');
let currentHash = 'old_hash_value';

// 2. 监听消息
socket.onmessage = function(event) {
  const msg = JSON.parse(event.data);
  
  if (msg.type === 'hash') {
    currentHash = msg.data;
  } else if (msg.type === 'ok') {
    // 收到更新完成信号，开始热更新逻辑
    hotCheck();
  }
};

function hotCheck() {
  console.log('检测到更新，准备拉取新代码...');
  // 实际 Webpack 会在这里：
  // 1. fetch('/hash.hot-update.json') -> 拿到变动的模块ID
  // 2. loadScript('/hash.hot-update.js') -> 拿到新模块代码
  // 3. hotApply() -> 执行替换
  
  // 模拟热更新操作
  hotDownloadManifest().then(hotDownloadUpdateChunk);
}

核心：如何在浏览器端替换代码

这是HMR最关键的一步。回顾之前的打包结构，所有模块都存在 __webpack_modules__ 对象中。热更新的本质就是修改这个对象的键值对。

假设更新前的 bundle.js 运行时结构：

var __webpack_modules__ = {
  "./src/title.js": function(module, exports) {
    module.exports = "Old Title";
  }
};
// 缓存
var __webpack_module_cache__ = {
  "./src/title.js": { exports: "Old Title", loaded: true }
};

更新发生时 (hotApply 的简化逻辑)：

// 这是一个由 JSONP 加载的新代码块
function webpackHotUpdateCallback(chunkId, moreModules) {
  // moreModules 包含了新的模块代码
  // 例如: { "./src/title.js": function() { module.exports = "New Title"; } }
  
  for (let moduleId in moreModules) {
    // 1. 覆盖旧的模块定义
    __webpack_modules__[moduleId] = moreModules[moduleId];
    
    // 2. 删除旧的缓存（关键）
    // 下次 require 这个模块时，会重新执行新函数
    delete __webpack_module_cache__[moduleId];
    
    // 3. 执行 accept 回调（如果有）
    if (hot._acceptedDependencies[moduleId]) {
      hot._acceptedDependencies[moduleId]();
    }
  }
}

总结操作：

1. 覆盖：用新函数覆盖 __webpack_modules__ 中的旧函数。
2. 清缓存：删除 __webpack_module_cache__ 中的缓存。
3. 重执行：当父模块再次执行 __webpack_require__('./src/title.js') 时，会拿到最新的代码。

四、module.hot.accept 与 冒泡机制

仅仅替换模块定义是不够的，如果页面已经渲染了 "Old Title"，仅仅替换函数的定义，页面文字不会自动变。需要代码主动响应这个变化。

开发者代码中的设置

在入口文件（如 index.js）中：

import title from './title.js';

document.body.innerText = title;

// 必须添加这段代码才能实现 HMR，否则会回退到整页刷新
if (module.hot) {
  // 注册回调：当 title.js 发生变化时执行
  module.hot.accept(['./title.js'], () => {
    // 重新获取新内容
    const newTitle = require('./title.js'); 
    // 执行具体的 DOM 更新逻辑
    document.body.innerText = newTitle; 
  });
}

冒泡机制 (Bubbling)

如果 title.js 变了，但 title.js 没有 module.hot.accept，Webpack 会怎么做？

1. 检查自身：title.js 有 accept 吗？没有。
2. 向上查找：谁引用了 title.js？是 index.js。
3. 检查父级：index.js 有没有 accept('./title.js')？

• • 有：执行 index.js 中定义的回调。更新结束。
  • 没有：继续向上查找 index.js 的父级。

4. 顶层失败：如果一直冒泡到入口文件（Entry）都没有被 accept 捕获，HMR 宣告失败，触发 window.location.reload() 进行全量刷新。

4.3 为什么Vue/React开发时不需要手写accept？

因为 vue-loader 或 react-refresh 自动在编译时注入了 module.hot.accept 代码。

例如 vue-loader 转换后的代码大致如下：

// vue-loader 自动注入的代码
import { render } from './App.vue?vue&type=template';
// ...
export default component.exports;

if (module.hot) {
  module.hot.accept(); // 接受自身更新
  module.hot.accept('./App.vue?vue&type=template', () => {
    // 当模板更新时，重新渲染组件，保留状态
    api.rerender('component-id', render); 
  });
}

五、总结 Webpack HMR 实现链

1. 监听：Compiler 监听到文件修改。
2. 生成：Compiler 生成 Manifest 和 Update Chunk。
3. 通知：Server 通过 WebSocket 通知 Client "有新 Hash"。
4. 下载：Client 通过 JSONP 下载新代码块。
5. 替换：Client 运行时更新 __webpack_modules__ 并清除缓存。
6. 响应：通过 module.hot.accept 定义的回调函数，执行具体的业务逻辑更新（如重绘 DOM）。

Webpack Plugin实现

一、Plugin的核心作用与Loader的区别

1.1 什么是Plugin

Plugin不处理具体的模块内容，而是监听Webpack构建过程中的生命周期事件（Hooks），在特定的时刻执行特定的逻辑，从而改变构建结果。

1.2 Plugin与Loader的直观对比

特性	Loader	Plugin
作用对象	单个文件 (如 .css, .vue)	整个构建过程 (Compiler)
功能	转换代码 (less -> css)	打包优化、资源管理、环境变量注入
运行时机	解析模块依赖时	构建流程的任意时刻 (启动、编译、发射、结束)
配置方式	module.rules 数组	plugins 数组

1.3 常见的Plugin功能

• 打包前：清除 dist 目录 (CleanWebpackPlugin)。
• 编译中：定义全局变量 (DefinePlugin)。
• 打包后：生成 index.html 并自动插入JS脚本 (HtmlWebpackPlugin)。
• 结束时：压缩CSS/JS代码，上传资源到CDN。

二、Plugin的基本结构(自测：说出Plugin的固定格式)

2.1 基础代码结构

Webpack的Plugin是一个类（Class），它必须包含一个 apply 方法。

class MyPlugin {
  // 1. 接收配置参数
  constructor(options) {
    this.options = options;
  }

  // 2. 必须包含 apply 方法，接收 compiler 对象
  apply(compiler) {
    // 3. 注册钩子，监听事件 (例如 'done' 表示构建完成)
    compiler.hooks.done.tap('MyPlugin', (stats) => {
      console.log('构建完成！');
    });
  }
}

module.exports = MyPlugin;

2.2 使用方式

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

module.exports = {
  plugins: [
    new MyPlugin({ param: 'value' }) // 实例化插件
  ]
};

三、两个核心对象：Compiler与Compilation

在编写Plugin时，必须区分两个对象：

3.1 Compiler (编译器)

• 定义：代表了完整的 Webpack 环境配置。
• 生命周期：Webpack 启动时创建，直到进程结束。它是全局唯一的。
• 作用：可以访问所有的配置信息（entry, output, loaders等），用于注册全局级别的钩子。

3.2 Compilation (编译过程)

• 定义：代表了一次具体的构建过程。
• 生命周期：每次检测到文件变化（热更新）时，都会创建一个新的 compilation 对象。
• 作用：包含了当前的模块资源、编译生成的文件（assets）、依赖关系图。如果要修改打包输出的内容，必须操作 compilation。

四、手写实现一个文件清单插件 (FileListPlugin)

4.1 需求描述

我们需要实现一个插件，在打包生成文件之前，自动生成一个 file-list.md 文件。 该文件记录所有打包输出的文件名和文件大小。

4.2 实现步骤

1. 监听钩子：使用 emit 钩子。这个时刻编译已完成，文件即将输出到磁盘，但还未输出。这是修改输出资源的最后机会。
2. 获取资源：从 compilation.assets 获取所有待输出的文件。
3. 生成内容：遍历资源，拼接文件名和大小。
4. 添加资源：将新生成的 file-list.md 添加到 compilation.assets 中。

4.3 代码实现

class FileListPlugin {
  constructor(options) {
    // 允许用户配置输出的文件名，默认为 'file-list.md'
    this.filename = options && options.filename ? options.filename : 'file-list.md';
  }

  apply(compiler) {
    // 1. 注册 emit 钩子（这是一个异步钩子，使用 tapAsync）
    compiler.hooks.emit.tapAsync('FileListPlugin', (compilation, callback) => {
      
      let fileList = '# Bundled Files

';

      // 2. 遍历 compilation.assets (包含所有即将输出的文件)
      for (let filename in compilation.assets) {
        // 获取文件来源对象
        const source = compilation.assets[filename];
        // 获取文件大小
        const size = source.size();
        
        fileList += `- ${filename}: ${size} bytes
`;
      }

      // 3. 将生成的内容添加到输出资源列表
      compilation.assets[this.filename] = {
        // 返回文件内容
        source: function() {
          return fileList;
        },
        // 返回文件大小
        size: function() {
          return fileList.length;
        }
      };

      // 4. 异步处理完成，必须调用 callback 告诉 Webpack 继续执行
      callback();
    });
  }
}

module.exports = FileListPlugin;

4.4 模拟运行效果

假设打包输出了 bundle.js (1000 bytes) 和 style.css (500 bytes)，配置插件后，dist 目录下会多出一个 file-list.md：

# Bundled Files

- bundle.js: 1000 bytes
- style.css: 500 bytes

五、常用生命周期钩子(Hooks)一览

Webpack 基于 Tapable 库实现了事件流。以下是开发 Plugin 最常用的几个钩子：

钩子名称	归属对象	时机	常用场景	同步/异步
entryOption	compiler	初始化配置后	读取或修改 Entry 配置	Sync
compile	compiler	开始编译前	提示“开始构建”	Sync
compilation	compiler	编译过程创建时	注册更细粒度的 compilation 钩子	Sync
emit	compiler	生成资源到目录前	修改文件内容、添加新文件 (最常用)	Async
done	compiler	编译完成	提示构建结束、上传资源、分析耗时	Async

注册方式的区别：

• 同步钩子：tap('PluginName', (params) => { ... })
• 异步钩子：
  • tapAsync('PluginName', (params, callback) => { ... callback(); })
  • tapPromise('PluginName', (params) => { return Promise.resolve(); })

六、总结

Webpack Plugin 的实现核心链条：

1. 类结构：定义一个类，包含 apply(compiler) 方法。
2. 事件监听：通过 compiler.hooks 监听 Webpack 的生命周期事件。
3. 资源操作：
   • 如果只关注流程监控（如 build 进度），操作 compiler。
   • 如果要修改产物（如添加文件、压缩代码），操作 compilation.assets。
4. 流程控制：如果是异步钩子，处理完逻辑后必须调用 callback 或返回 Promise，否则构建会卡死。

Webpack 模块联邦 (Module Federation) 实现

一、解决的具体问题

在模块联邦出现之前，跨项目共享代码主要有两种方式，各有明显的弊端：

1. NPM 包模式

   • 流程：项目 B 修改组件 -> 打包发布到 NPM -> 项目 A 更新 package.json -> 项目 A 重新安装依赖 -> 项目 A 重新打包发布。
   • 缺点：更新流程长，无法实现热插拔，所有依赖在构建时必须确定。

2. Iframe 或 Script 标签引入

   • 流程：项目 A 直接加载项目 B 的打包文件。
   • 缺点：完全隔离（Iframe）导致上下文不通；或者没有依赖共享机制（Script 标签），导致项目 A 和项目 B 各自加载了一份 React，页面体积倍增，且可能导致 React 实例冲突（Hooks 报错）。

模块联邦解决的问题： 在浏览器运行时，项目 A 可以直接引用 项目 B 构建好的代码，并且双方共享底层的依赖（如 React），避免重复加载。

二、基础配置与概念

模块联邦引入了三个核心概念：Host（消费者）、Remote（提供者）、Shared（共享依赖）。

假设场景：

• App 1 (Remote): 端口 3001，提供一个 Button 组件。
• App 2 (Host): 端口 3002，想要使用 App 1 的 Button。

2.1 提供方 (App 1) 配置

// webpack.config.js (App 1)
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  // ...其他配置
  plugins: [
    new ModuleFederationPlugin({
      name: 'app1',                  // 唯一标识，对应全局变量 window.app1
      filename: 'remoteEntry.js',    // 暴露出的入口文件名称
      exposes: {
        './Button': './src/Button',  // 映射：外部引入路径 -> 内部文件路径
      },
      shared: { react: { singleton: true }, 'react-dom': { singleton: true } },
    }),
  ],
};

2.2 消费方 (App 2) 配置

// webpack.config.js (App 2)
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'app2',
      remotes: {
        // 键名 'app1'：在代码中 import 的前缀
        // 键值 'app1@...'：远程应用的 name + 远程应用的地址
        app1: 'app1@http://localhost:3001/remoteEntry.js',
      },
      shared: { react: { singleton: true }, 'react-dom': { singleton: true } },
    }),
  ],
};

2.3 消费方代码使用

// App 2 的业务代码
import React, { Suspense } from 'react';

// 像引入本地模块一样引入远程模块
// 'app1' 对应配置中的 remotes 键名
// 'Button' 对应 App 1 exposes 的键名
const RemoteButton = React.lazy(() => import('app1/Button'));

function App() {
  return (
    <Suspense fallback="Loading...">
      <RemoteButton />
    </Suspense>
  );
}

三、核心原理：remoteEntry.js 是什么？

当 App 1 构建时，Webpack 会生成一个特殊的入口文件 remoteEntry.js。这是模块联邦通信的桥梁。

这个文件包含三个主要部分：

1. 模块映射表 (Module Map)：记录了 ./Button 对应的是哪个 chunk 文件（例如 src_Button_js.js）。
2. 获取函数 (Get)：用于根据路径加载对应的模块。
3. 初始化函数 (Init)：用于接收 Host 传递过来的共享依赖（Shared Scope）。

浏览器运行时流程：

1. App 2 加载 http://localhost:3001/remoteEntry.js。
2. remoteEntry.js 执行，在全局 window 上挂载一个变量 app1。
3. App 2 调用 window.app1.init()，将自己（App 2）的 React 版本放入共享作用域。
4. App 2 调用 window.app1.get('./Button')。
5. App 1 检查共享作用域，发现已有 React，便不再加载自己的 React，而是直接下载 Button 的代码并返回。

四、手写简易模块联邦实现

为了理解 Webpack 内部是如何实现的，我们模拟一下 Host 和 Remote 在浏览器端的交互逻辑。

4.1 模拟 Remote (App 1) 的 remoteEntry.js

这是一个立即执行函数，目的是在全局注册接口。

// 模拟 app1/remoteEntry.js
var app1_modules = {
  './Button': () => {
    // 实际场景这里是通过 JSONP 加载真实文件
    console.log("加载 App1 的 Button 组件");
    return {
      default: "我是来自 App1 的按钮"
    };
  }
};

// 共享作用域容器
var sharedScope = {};

// 在 window 上挂载全局对象
window.app1 = {
  // 1. get: 供 Host 获取模块
  get: function(moduleName) {
    return new Promise((resolve) => {
      if (app1_modules[moduleName]) {
        // 返回模块的工厂函数
        resolve(() => app1_modules[moduleName]());
      } else {
        resolve(null);
      }
    });
  },

  // 2. init: 供 Host 初始化共享依赖
  init: function(scope) {
    // 将 Host 传来的 scope 合并到自己的 scope 中
    sharedScope = scope;
    console.log("App1 初始化完成，已接收共享依赖", scope);
    return Promise.resolve();
  }
};

4.2 模拟 Host (App 2) 的加载逻辑

Host 需要先加载远程脚本，然后按顺序调用 init 和 get。

// 模拟 Webpack 内部加载远程模块的逻辑

// 1. 定义加载脚本的辅助函数
function loadScript(url) {
  return new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.src = url;
    script.onload = resolve;
    script.onerror = reject;
    document.head.appendChild(script);
  });
}

// 2. 主流程
(async function() {
  // 步骤 A: 初始化 Host 自身的共享作用域
  const hostSharedScope = {
    react: { version: '17.0.2', loaded: true }
  };
  
  // 步骤 B: 加载 Remote 的入口文件
  await loadScript('http://localhost:3001/remoteEntry.js');
  
  // 此时 window.app1 已经存在
  const container = window.app1;
  
  // 步骤 C: 初始化容器 (交换共享依赖)
  // 告诉 app1："我有这些依赖，你看看能不能用，别自己重复加载了"
  await container.init(hostSharedScope);
  
  // 步骤 D: 获取组件
  const factory = await container.get('./Button');
  const module = factory();
  
  console.log("最终获取到的模块:", module.default);
})();

五、依赖共享的具体逻辑 (Singleton)

在 shared 配置中，最关键的是版本控制。Webpack 运行时会进行如下判断：

1. Host 端：我有 React 17.0.2。
2. Remote 端：我需要 React ^16.8.0。
3. 握手阶段 (init)：Remote 检查 Host 提供的 React 17.0.2 是否满足 ^16.8.0。
   • 满足：Remote 丢弃自己的 React 依赖，使用 Host 提供的全局 React 对象。
   • 不满足：Remote 坚持加载自己打包的 React 副本（除非配置了 singleton: true 且 strictVersion: true，此时会报错）。

实现简述： Webpack 维护了一个全局对象 __webpack_share_scopes__。init 函数的本质就是把不同应用的依赖对象合并到这个全局对象中，通过语义化版本（SemVer）比较函数来决定使用哪一个版本的库。

六、总结模块联邦

1. 去中心化：没有所谓的“主应用”，任何应用都可以同时是 Host 和 Remote。
2. 运行时加载：不同于 NPM 的构建时集成，WMF 是在页面打开时动态下载代码。
3. 双向接口：
   • init(scope)：输入接口，接收外部环境的共享依赖。
   • get(path)：输出接口，向外部暴露内部模块。
4. 本质：通过全局变量（window.app_name）建立通信协议，实现不同构建产物之间的互操作。