Vite 源码解析(4) - 开发服务篇

resolveHttpsConfig

// https 配置, 主要是证书
const httpsOptions = await resolveHttpsConfig(
  config.server.https,
  config.cacheDir
);
let { middlewareMode } = serverConfig;
if (middlewareMode === true) {
  middlewareMode = "ssr";
}

首先 vite 的开发环境是支持 https 的, 虽然绝大多数我们是用 localhost 的, 不过有些场景, 比如你依赖的三方服务, 必须使用 https, 否则没法调试, 那你就得支持 https 了. 该函数接收两个参数, 第一个 `ServerOptions` 是 node 标准库 https 的配置, 签名如下; 第二个是缓存文件的目录.

type ServerOptions = tls.SecureContextOptions &
  tls.TlsOptions &
  http.ServerOptions;

整个函数简单来讲就是你在配置里传了证书没, 没传就去缓存文件里找, 最后返回配置.

export async function resolveHttpsConfig(
  https: boolean | HttpsServerOptions | undefined,
  cacheDir: string
): Promise<HttpsServerOptions | undefined> {
  if (!https) return undefined;
  const httpsOption = isObject(https) ? { ...https } : {};
  const { ca, cert, key, pfx } = httpsOption;
  Object.assign(httpsOption, {
    ca: readFileIfExists(ca),
    cert: readFileIfExists(cert),
    key: readFileIfExists(key),
    pfx: readFileIfExists(pfx),
  });
  if (!httpsOption.key || !httpsOption.cert) {
    httpsOption.cert = httpsOption.key = await getCertificate(cacheDir);
  }
  return httpsOption;
}

`getCertificate` 就是用来获取缓存路径中的证书的, 如果没有, 就会调用 `createCertificate` 生成一个新的自签名证书, 这个不多说了, 毕竟不咋会, 匿了匿了. 总之 vite 就是一条龙服务, 你有就用你的, 顺带帮你验证下证书过没过期, 如果你没提供证书, 还帮你搞个自签名, 老铁们给尤雨溪双击 666.

async function getCertificate(cacheDir: string) {
  const cachePath = path.join(cacheDir, "_cert.pem");
  try {
    const [stat, content] = await Promise.all([
      fsp.stat(cachePath),
      fsp.readFile(cachePath, "utf8"),
    ]);
    if (Date.now() - stat.ctime.valueOf() > 30 * 24 * 60 * 60 * 1000) {
      throw new Error("cache is outdated.");
    }
    return content;
  } catch {
    const content = (await import("./certificate")).createCertificate();
    fsp
      .mkdir(cacheDir, { recursive: true })
      .then(() => fsp.writeFile(cachePath, content))
      .catch(() => {});
    return content;
  }
}

resolveHttpServer

// 一个三方库,用于把中间件和 server 关联起来, 最基本的支持 req, res, next, use, handle 等等
const middlewares = connect() as Connect.Server;
const httpServer = middlewareMode
  ? null
  : await resolveHttpServer(serverConfig, middlewares, httpsOptions);

下面是创建 http server, 如果是 http, 就直接用 `node:http` 的 `createServer`; 否则就是 https, 那么优先用 `node:http2`, 因为我们知道 http2 强制使用 https 的; 当然如果是代理, 就得用 `node:https`. 看了一下 issue 是这样解释的:

http-proxy (The underlying module which vite uses for proxy) does not support http2. You cannot use https with proxy as vite is now using Http2.

export async function resolveHttpServer(
  { proxy }: CommonServerOptions,
  app: Connect.Server,
  httpsOptions?: HttpsServerOptions
): Promise<HttpServer> {
  if (!httpsOptions) {
    const { createServer } = await import("http");
    return createServer(app);
  }
  // #484 fallback to http1 when proxy is needed.
  if (proxy) {
    const { createServer } = await import("https");
    return createServer(httpsOptions, app);
  } else {
    const { createSecureServer } = await import("http2");
    return createSecureServer(
      {
        // Manually increase the session memory to prevent 502 ENHANCE_YOUR_CALM
        // errors on large numbers of requests
        maxSessionMemory: 1000,
        ...httpsOptions,
        allowHTTP1: true,
      },
      // @ts-expect-error TODO: is this correct?
      app
    ) as unknown as HttpServer;
  }
}

createWebSocketServer

const ws = createWebSocketServer(httpServer, config, httpsOptions);

当我们改动源码时, chokidar 会监听到文件变化, 然后交给 rollup 去做编译, 当编译完成后就要通知到前端进行热更新, 那么我们就需要一个 websocket 的服务, vite 使用了 ws 这个库, 而 `createWebSocketServer` 基本就是 ws 的封装. 当然要补充一个小知识, 就是 ws 的开启需要用 http 做为引导, http 返回 101 状态码后方可升级成 ws.

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

整个函数因为不复杂, 我们直接在源码上写注释.

export function createWebSocketServer(
  server: Server | null,
  config: ResolvedConfig,
  httpsOptions?: HttpsServerOptions
): WebSocketServer {
  let wss: WebSocketServerRaw;
  let httpsServer: Server | undefined = undefined;
  const hmr = isObject(config.server.hmr) && config.server.hmr;
  // 用户可以自行提供一个 server, 不过一般不会这么玩
  const hmrServer = hmr && hmr.server;
  const hmrPort = hmr && hmr.port;
  // TODO: the main server port may not have been chosen yet as it may use the next available
  const portsAreCompatible = !hmrPort || hmrPort === config.server.port;
  const wsServer = hmrServer || (portsAreCompatible && server);
  // 监听器, key 是事件名, value 是 WebSocketCustomListener 格式的集合
  const customListeners = new Map<string, Set<WebSocketCustomListener<any>>>();
  const clientsMap = new WeakMap<WebSocketRaw, WebSocketClient>();
  if (wsServer) {
    wss = new WebSocketServerRaw({ noServer: true });
    // 如果用户自行提供了 http server, 那么监听到 101 状态码, 就升级成 ws
    wsServer.on("upgrade", (req, socket, head) => {
      // 如果 sec-websocket-protocol 为 vite-hmr, 也就是 vite 的热更新协议, 那么就接受
      // 这块代码写的很严谨, 为了防止恰好命中了其他 http 过来的 101
      if (req.headers["sec-websocket-protocol"] === HMR_HEADER) {
        // 升级完协议后就正式连接到 ws 了
        wss.handleUpgrade(req, socket as Socket, head, (ws) => {
          wss.emit("connection", ws, req);
        });
      }
    });
  } else {
    const websocketServerOptions: ServerOptions = {};
    const port = hmrPort || 24678;
    const host = (hmr && hmr.host) || undefined;
    if (httpsOptions) {
      // if we're serving the middlewares over https, the ws library doesn't support automatically creating an https server, so we need to do it ourselves
      // create an inline https server and mount the websocket server to it
      // 因为 ws 没提供 https 的 server, 需要自己起一个
      httpsServer = createHttpsServer(httpsOptions, (req, res) => {
        // 426 Upgrade Required 表示服务器拒绝处理客户端使用当前协议发送的请求, 但是可以接受其使用升级后的协议发送的请求
        // 不过 STATUS_CODES[statusCode] 这个操作没搞懂, 肯定不是 undefiend 啊? 我给提 pr 那哥们留了个 comment, 先留个 TODO:
        const statusCode = 426;
        const body = STATUS_CODES[statusCode];
        if (!body)
          throw new Error(
            `No body text found for the ${statusCode} status code`
          );
        res.writeHead(statusCode, {
          "Content-Length": body.length,
          "Content-Type": "text/plain",
        });
        res.end(body);
      });
      httpsServer.listen(port, host);
      websocketServerOptions.server = httpsServer;
    } else {
      // we don't need to serve over https, just let ws handle its own server
      websocketServerOptions.port = port;
      if (host) {
        websocketServerOptions.host = host;
      }
    }
    // vite dev server in middleware mode
    // 最终我们跑起了一个 WebSocket 的服务, 默认端口是 24678
    wss = new WebSocketServerRaw(websocketServerOptions);
  }
  // 接下来就是对 ws 的封装了
  wss.on("connection", (socket) => {
    // message 事件是 ws 接收到数据后触发的事件
    socket.on("message", (raw) => {
      // 如果没有事件监听器, 收到消息也处理不了, 直接 return
      if (!customListeners.size) return;
      // 拿到解析后的数据, 校验合法性
      // parsed 就是当源码改了, chokidar 通过 rollup 改完之后, 发送给 ws 的数据
      let parsed: any;
      try {
        parsed = JSON.parse(String(raw));
      } catch {}
      if (!parsed || parsed.type !== "custom" || !parsed.event) return;
      // 根据 event 名去事件监听器集合中查找相应的监听器集合
      const listeners = customListeners.get(parsed.event);
      // 如果监听器集合没有, 直接 return
      if (!listeners?.size) return;
      // getSocketClient 这个函数下面有解释, 就是给 client 封装一层, 保证发送数据的一致性
      const client = getSocketClient(socket);
      // 遍历监听器集合, 逐一执行
      listeners.forEach((listener) => listener(parsed.data, client));
    });
    socket.send(JSON.stringify({ type: "connected" }));
    // 如果编译出错了啥的, 也把错误暴露给前端
    if (bufferedError) {
      socket.send(JSON.stringify(bufferedError));
      bufferedError = null;
    }
  });
  // 监听失败事件
  wss.on("error", (e: Error & { code: string }) => {
    if (e.code === "EADDRINUSE") {
      config.logger.error(
        colors.red(`WebSocket server error: Port is already in use`),
        { error: e }
      );
    } else {
      config.logger.error(
        colors.red(`WebSocket server error:\n${e.stack || e.message}`),
        { error: e }
      );
    }
  });
  // Provide a wrapper to the ws client so we can send messages in JSON format
  // To be consistent with server.ws.send
  // 对 ws 客户端进行封装, 保证发送一致性的 json 格式的数据
  // 也就是说, 对于每个新进来的 ws 实例, 都对它的 send 方法(发送给客户端的 payload)进行了封装, 使其发送的数据格式一致
  function getSocketClient(socket: WebSocketRaw) {
    if (!clientsMap.has(socket)) {
      clientsMap.set(socket, {
        send: (...args) => {
          let payload: HMRPayload;
          if (typeof args[0] === "string") {
            payload = {
              type: "custom",
              event: args[0],
              data: args[1],
            };
          } else {
            payload = args[0];
          }
          socket.send(JSON.stringify(payload));
        },
        socket,
      });
    }
    return clientsMap.get(socket)!;
  }
  // On page reloads, if a file fails to compile and returns 500, the server
  // sends the error payload before the client connection is established.
  // If we have no open clients, buffer the error and send it to the next
  // connected client.
  let bufferedError: ErrorPayload | null = null;
  // 下面大家就太熟悉了, 一个典型 EventEmitter
  // 尤雨溪确实好这口, vue 源码里我记得也有个类似的东西, 我们就不多说了
  return {
    on: ((event: string, fn: () => void) => {
      if (wsServerEvents.includes(event)) wss.on(event, fn);
      else {
        if (!customListeners.has(event)) {
          customListeners.set(event, new Set());
        }
        customListeners.get(event)!.add(fn);
      }
    }) as WebSocketServer["on"],
    off: ((event: string, fn: () => void) => {
      if (wsServerEvents.includes(event)) {
        wss.off(event, fn);
      } else {
        customListeners.get(event)?.delete(fn);
      }
    }) as WebSocketServer["off"],
    get clients() {
      return new Set(Array.from(wss.clients).map(getSocketClient));
    },
    send(...args: any[]) {
      let payload: HMRPayload;
      if (typeof args[0] === "string") {
        payload = {
          type: "custom",
          event: args[0],
          data: args[1],
        };
      } else {
        payload = args[0];
      }
      if (payload.type === "error" && !wss.clients.size) {
        bufferedError = payload;
        return;
      }
      const stringified = JSON.stringify(payload);
      wss.clients.forEach((client) => {
        // readyState 1 means the connection is open
        if (client.readyState === 1) {
          client.send(stringified);
        }
      });
    },
    close() {
      return new Promise((resolve, reject) => {
        wss.clients.forEach((client) => {
          client.terminate();
        });
        wss.close((err) => {
          if (err) {
            reject(err);
          } else {
            if (httpsServer) {
              httpsServer.close((err) => {
                if (err) {
                  reject(err);
                } else {
                  resolve();
                }
              });
            } else {
              resolve();
            }
          }
        });
      });
    },
  };
}

chokidar

在 server 搭建好后, 就需要使用 chokidar 监听文件变化, 来触发 hmr.

const { ignored = [], ...watchOptions } = serverConfig.watch || {};
// chokidar 实例
const watcher = chokidar.watch(path.resolve(root), {
  ignored: [
    "**/node_modules/**",
    "**/.git/**",
    ...(Array.isArray(ignored) ? ignored : [ignored]),
  ],
  ignoreInitial: true,
  ignorePermissionErrors: true,
  disableGlobbing: true,
  ...watchOptions,
}) as FSWatcher;
// 监听文件变化
watcher.on("change", async (file) => {
  file = normalizePath(file);
  // 如果是 package.json 的变化, 需要更新 packageCache 的数据
  if (file.endsWith("/package.json")) {
    return invalidatePackageData(packageCache, file);
  }
  // invalidate module graph cache on file change
  // 当有源码文件变化, 重塑模块依赖图
  moduleGraph.onFileChange(file);
  if (serverConfig.hmr !== false) {
    try {
      // 并进行 hmr, 这个我们下一章主讲
      await handleHMRUpdate(file, server);
    } catch (err) {
      ws.send({
        type: "error",
        err: prepareError(err),
      });
    }
  }
});

server 实例

至此我们就跑起来一个服务, 下面是它最终的实例, 这里面的大部分方法都跟 hmr 有关, 我们只是简单贴一下, 下一章重点来讲 hmr. 至于 ssr, 由于官方还不稳定, 等稳定了后面再填坑.

const server: ViteDevServer = {
  config, // 配置
  middlewares, // 中间件
  httpServer, // http 服务
  watcher, // chokidar
  pluginContainer: container, // 插件容器
  ws, // ws 模块
  moduleGraph, // 模块依赖图
  ssrTransform(code: string, inMap: SourceMap | null, url: string) {
    return ssrTransform(code, inMap, url, {
      json: { stringify: server.config.json?.stringify },
    });
  },
  transformRequest(url, options) {
    // 当有 bundle 发生变化时, 转换成请求
    return transformRequest(url, server, options);
  },
  transformIndexHtml: null!, // to be immediately set
  async ssrLoadModule(url, opts?: { fixStacktrace?: boolean }) {
    await updateCjsSsrExternals(server);
    return ssrLoadModule(
      url,
      server,
      undefined,
      undefined,
      opts?.fixStacktrace
    );
  },
  ssrFixStacktrace(e) {
    if (e.stack) {
      const stacktrace = ssrRewriteStacktrace(e.stack, moduleGraph);
      rebindErrorStacktrace(e, stacktrace);
    }
  },
  ssrRewriteStacktrace(stack: string) {
    return ssrRewriteStacktrace(stack, moduleGraph);
  },
  listen(port?: number, isRestart?: boolean) {
    return startServer(server, port, isRestart);
  },
  async close() {
    if (!middlewareMode) {
      process.off("SIGTERM", exitProcess);
      if (process.env.CI !== "true") {
        process.stdin.off("end", exitProcess);
      }
    }
    await Promise.all([
      watcher.close(),
      ws.close(),
      container.close(),
      closeHttpServer(),
    ]);
  },
  printUrls() {
    if (httpServer) {
      printCommonServerUrls(httpServer, config.server, config);
    } else {
      throw new Error("cannot print server URLs in middleware mode.");
    }
  },
  async restart(forceOptimize?: boolean) {
    if (!server._restartPromise) {
      server._forceOptimizeOnRestart = !!forceOptimize;
      server._restartPromise = restartServer(server).finally(() => {
        server._restartPromise = null;
        server._forceOptimizeOnRestart = false;
      });
    }
    return server._restartPromise;
  },
  _ssrExternals: null,
  _restartPromise: null,
  _importGlobMap: new Map(),
  _forceOptimizeOnRestart: false,
  _pendingRequests: new Map(),
};

configureServer

由于 vite 的插件系统提供了 `configureServer` 钩子, configureServer 钩子将在内部中间件被安装前调用, 所以自定义的中间件将会默认会比内部中间件早运行. 如果你想注入一个在内部中间件之后运行的中间件, 你可以从 configureServer 返回一个函数, 将会在内部中间件安装后被调用.

// apply server configuration hooks from plugins
const postHooks: ((() => void) | void)[] = [];
for (const plugin of config.plugins) {
  if (plugin.configureServer) {
    postHooks.push(await plugin.configureServer(server));
  }
}

middleware 总览

解析来 vite 将执行一票内置中间件, 我们先看个概览, 下面逐一学习.

// Internal middlewares ------------------------------------------------------
// request timer
// 在 debug 模式统计一次请求耗费的时间
if (process.env.DEBUG) {
  middlewares.use(timeMiddleware(root));
}
// cors (enabled by default)
// 处理跨域
const { cors } = serverConfig;
if (cors !== false) {
  middlewares.use(corsMiddleware(typeof cors === "boolean" ? {} : cors));
}
// proxy
// 处理代理
const { proxy } = serverConfig;
if (proxy) {
  middlewares.use(proxyMiddleware(httpServer, proxy, config));
}
// base
// base 是开发或生产环境服务的公共基础路径, 默认是  '/', 如果用户设置了其他路径, 需要藉此进行调整
if (config.base !== "/") {
  middlewares.use(baseMiddleware(server));
}
// open in editor support
// 这个库是 vite 直接从 react-dev-utils 里拿的, 用于前端框架在报错的时候, 会在浏览器出个弹窗, 展示错误堆栈(行数, 列数, 路径)
// 你点击错误, 这个中间件帮助你打开编辑器, 并定位到那一行
// (其实挺鸡肋的)
middlewares.use("/__open-in-editor", launchEditorMiddleware());
// serve static files under /public
// this applies before the transform middleware so that these files are served
// as-is without transforms.
// 保护 public 文件夹下的文件不被编译到
if (config.publicDir) {
  middlewares.use(
    servePublicMiddleware(config.publicDir, config.server.headers)
  );
}
// main transform middleware
// 转换(src 下的)源码 / 资源
middlewares.use(transformMiddleware(server));
// serve static files
middlewares.use(serveRawFsMiddleware(server));
middlewares.use(serveStaticMiddleware(root, server));
const isMiddlewareMode = middlewareMode && middlewareMode !== "html";
// spa fallback
if (config.spa && !isMiddlewareMode) {
  middlewares.use(spaFallbackMiddleware(root));
}
// run post config hooks
// This is applied before the html middleware so that user middleware can
// serve custom content instead of index.html.
// 执行后置自定义 server 钩子
postHooks.forEach((fn) => fn && fn());
if (config.spa && !isMiddlewareMode) {
  // transform index.html
  middlewares.use(indexHtmlMiddleware(server));
}
if (!isMiddlewareMode) {
  // handle 404s
  // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`
  // 简单地把状态码设置为 404
  middlewares.use(function vite404Middleware(_, res) {
    res.statusCode = 404;
    res.end();
  });
}
// error handler
// 返回一个状态码为 500 的错误 html 页面
middlewares.use(errorMiddleware(server, !!middlewareMode));

关于前几个中间件, `timeMiddleware`, `corsMiddleware`, `proxyMiddleware`, `baseMiddleware`, `launchEditorMiddleware`, 以及 `vite404Middleware`, `errorMiddleware` 就不多说, 很常见也很通用, 直接看注释即可. 我们主要来分析下面两组:

• 跟 index.html 有关的: `transformMiddleware`,`spaFallbackMiddleware`, `indexHtmlMiddleware`
• 跟静态文件有关的: `servePublicMiddleware`, `serveRawFsMiddleware`, `serveStaticMiddleware`

跟 index.html 相关的中间件

spaFallbackMiddleware

这个中间件的重点是 connect-history-api-fallback 这个库. 我们知道对于单页应用, 路由实际都是假的, 因此你刷新一下页面, 就到 404 了, 而这个库的目的就是在刷新后, 重写路由到 index.html 上, 这样就不会导致资源丢失了.

import fs from "fs";
import path from "path";
import history from "connect-history-api-fallback";
import type { Connect } from "types/connect";
import { createDebugger } from "../../utils";
export function spaFallbackMiddleware(
  root: string
): Connect.NextHandleFunction {
  const historySpaFallbackMiddleware = history({
    logger: createDebugger("vite:spa-fallback"),
    // support /dir/ without explicit index.html
    rewrites: [
      {
        from: /\/$/,
        to({ parsedUrl }: any) {
          const rewritten =
            decodeURIComponent(parsedUrl.pathname) + "index.html";
          if (fs.existsSync(path.join(root, rewritten))) {
            return rewritten;
          } else {
            return `/index.html`;
          }
        },
      },
    ],
  });
  // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`
  return function viteSpaFallbackMiddleware(req, res, next) {
    return historySpaFallbackMiddleware(req, res, next);
  };
}

顺便提一嘴, 在最终线上, 你也要在 nginx 配置好路由重写, 否则也会 404.

try_files {path} /index.html

indexHtmlMiddleware

在讲这个中间件之前, 我们先看看在 public 文件夹下初始化的 index.html 文件是这样婶的:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/src/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

但是我们在浏览器审查元素, 它变成了如下的样子:

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="module" src="/@vite/client"></script>
    <script type="module">
      import RefreshRuntime from "/@react-refresh";
      RefreshRuntime.injectIntoGlobalHook(window);
      window.$RefreshReg$ = () => {};
      window.$RefreshSig$ = () => (type) => type;
      window.__vite_plugin_react_preamble_installed__ = true;
    </script>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/src/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

之所以增加了两个 script 标签, 就是由 `indexHtmlMiddleware` 做到的, 它通过拦截 index.html, 然后根据传入的 hooks(plugin), 将 index.html 进行一番改造, 比如注入 `vite/client`, `react-fast-refresh` 等等. 上面我们在讲 spaFallbackMiddleware 时知道, 所有前端路由都被处理成 `/index.html`. 因此这个中间件首先找到 index.html 的绝对路径, 然后读取它. 再通过 `transformIndexHtml` 将其转换后, 通过 `send` 发送给前端.

export function indexHtmlMiddleware(
  server: ViteDevServer
): Connect.NextHandleFunction {
  // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`
  return async function viteIndexHtmlMiddleware(req, res, next) {
    if (res.writableEnded) {
      return next();
    }
    const url = req.url && cleanUrl(req.url);
    // spa-fallback always redirects to /index.html
    // 所有前端路由都被处理成 `/index.html`
    // 此外, 这里很严谨地判断了 sec-fetch-dest, 这是一个由浏览器发起的请求头, 这个请求头明确告知客户端需要什么类型的文件
    // 由于是 sec(security) 开头, 客户端是无法篡改的, 详情可以看 https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Mode
    if (url?.endsWith(".html") && req.headers["sec-fetch-dest"] !== "script") {
      const filename = getHtmlFilename(url, server);
      if (fs.existsSync(filename)) {
        try {
          // 获取 index.html 的内容
          let html = fs.readFileSync(filename, "utf-8");
          // 转换 html
          html = await server.transformIndexHtml(url, html, req.originalUrl);
          return send(req, res, html, "html", {
            headers: server.config.server.headers,
          });
        } catch (e) {
          return next(e);
        }
      }
    }
    next();
  };
}

回想 `createServer` 函数, 有一段这样的代码:

server.transformIndexHtml = createDevHtmlTransformFn(server);

可见, 重点就是 `createDevHtmlTransformFn` 个函数了, 它首先用 `resolveHtmlTransforms` 函数, 根据 enforce 拿到前置和后置 hooks. 然后通过 `applyHtmlTransforms` 方法处理 index.html 的代码. 下面我们细说这两个函数.

export function createDevHtmlTransformFn(
  server: ViteDevServer
): (url: string, html: string, originalUrl: string) => Promise<string> {
  const [preHooks, postHooks] = resolveHtmlTransforms(server.config.plugins);
  return (url: string, html: string, originalUrl: string): Promise<string> => {
    return applyHtmlTransforms(html, [...preHooks, devHtmlHook, ...postHooks], {
      path: url,
      filename: getHtmlFilename(url, server), // 绝对路径
      server,
      originalUrl,
    });
  };
}

下面列出了 `plugin.transformIndexHtml` 的函数签名. 可见它要么是个函数, 要么是个对象: 如果是函数的话就放在 postHooks 中; 如果是个对象, 会根据 `enforce` 属性决定它应该放在 preHooks 还是 postHooks 中.

export type IndexHtmlTransform =
  | IndexHtmlTransformHook
  | {
      enforce?: "pre" | "post";
      transform: IndexHtmlTransformHook;
    };

export function resolveHtmlTransforms(
  plugins: readonly Plugin[]
): [IndexHtmlTransformHook[], IndexHtmlTransformHook[]] {
  const preHooks: IndexHtmlTransformHook[] = [];
  const postHooks: IndexHtmlTransformHook[] = [];
  for (const plugin of plugins) {
    const hook = plugin.transformIndexHtml;
    if (hook) {
      if (typeof hook === "function") {
        postHooks.push(hook);
      } else if (hook.enforce === "pre") {
        preHooks.push(hook.transform);
      } else {
        postHooks.push(hook.transform);
      }
    }
  }
  return [preHooks, postHooks];
}

比如是个 react 项目, 它会引入 `@vitejs/plugin-react-refresh` 这个 plugin, 然后经过一系列操作, 在 index.html 注入以下代码, 因为这个 plugin 有个 `preambleCode` 字符串, 这个字符串正是 `@react-refresh` 的代码.

<head>
  ...
  <script type="module" src="/@vite/client"></script>
  <script type="module">
    import RefreshRuntime from "/@react-refresh";
    RefreshRuntime.injectIntoGlobalHook(window);
    window.$RefreshReg$ = () => {};
    window.$RefreshSig$ = () => (type) => type;
    window.__vite_plugin_react_preamble_installed__ = true;
  </script>
  ...
</head>

接下来我们看一下 `applyHtmlTransforms`, 它根据上面已经排序好的 hooks 依次执行, 它返回的是 `IndexHtmlTransformResult`. 我们先看一下相关 hook 的签名.

export type IndexHtmlTransformHook = (
  html: string,
  ctx: IndexHtmlTransformContext
) => IndexHtmlTransformResult | void | Promise<IndexHtmlTransformResult | void>;
export type IndexHtmlTransformResult =
  | string
  | HtmlTagDescriptor[]
  | {
      html: string;
      tags: HtmlTagDescriptor[];
    };
export interface HtmlTagDescriptor {
  tag: string;
  attrs?: Record<string, string | boolean | undefined>;
  children?: string | HtmlTagDescriptor[];
  /**
   * default: 'head-prepend'
   */
  injectTo?: "head" | "body" | "head-prepend" | "body-prepend";
}

`IndexHtmlTransformResult` 有可能是字符串, 数组或者对象:

• 如果是字符串, 那么直接赋值给最终 html 字符串
• 如果是数组, 那就先赋值给 tags 变量, 等待处理
• 如果是对象, 那就把 html 属性赋值给 html 变量, tags 属性赋值给 tags 变量, 等待处理 接下来就要对 tags 进行遍历, 根据 tag 的不同的类型, 也就是 `"head" | "body" | "head-prepend" | "body-prepend"`, 先放到不同的数组中, 然后通过 `injectToHead` 和 `injectToBody` 这两个函数, 将新增的标签及其内容添加到 html 中.

export async function applyHtmlTransforms(
  html: string,
  hooks: IndexHtmlTransformHook[],
  ctx: IndexHtmlTransformContext
): Promise<string> {
  for (const hook of hooks) {
    const res = await hook(html, ctx);
    if (!res) {
      continue;
    }
    if (typeof res === "string") {
      html = res;
    } else {
      let tags: HtmlTagDescriptor[];
      if (Array.isArray(res)) {
        tags = res;
      } else {
        html = res.html || html;
        tags = res.tags;
      }
      const headTags: HtmlTagDescriptor[] = [];
      const headPrependTags: HtmlTagDescriptor[] = [];
      const bodyTags: HtmlTagDescriptor[] = [];
      const bodyPrependTags: HtmlTagDescriptor[] = [];
      for (const tag of tags) {
        if (tag.injectTo === "body") {
          bodyTags.push(tag);
        } else if (tag.injectTo === "body-prepend") {
          bodyPrependTags.push(tag);
        } else if (tag.injectTo === "head") {
          headTags.push(tag);
        } else {
          headPrependTags.push(tag);
        }
      }
      html = injectToHead(html, headPrependTags, true);
      html = injectToHead(html, headTags);
      html = injectToBody(html, bodyPrependTags, true);
      html = injectToBody(html, bodyTags);
    }
  }
  return html;
}

关于 `injectToHead` 和 `injectToBody` 我们就不多讲了, 大抵就是把下面这个对象, 变成 `<script src="/@vite/client" type='module'></script>`, 然后插入到指定位置.

const o = {
  tag: "script",
  attrs: {
    type: "module",
    src: "/@vite/client",
  },
  injectTo: "head-prepend",
};

transformMiddleware

`transformMiddleware` 比较复杂, 大体来讲就是当浏览器成功加载了 index.html 之后, 肯定涉及一些源码的拉取; 此外, 用户交互也可能会涉及(比如切换了懒加载路由, 新页面肯定要下载对应的资源). vite 会通过原生 ESM 的方式请求源码文件, 但由于源码肯定不能被浏览器直接使用的(比如 tsx), 那这个中间件的目的就是拦截这些请求, 将这个被请求文件通过 esbuild 编译成浏览器支持的文件; 并会为该文件创建模块对象, 设置模块之间的依赖关系等等. 此外, 它还充分利用 http 的缓存机制, 来保证未过期文件的重复利用, 以提高速度. 关于 http 缓存可以看我的文章 [HTTP 系列] 第 3 篇 —— HTTP 缓存那些事.

export function transformMiddleware(
  server: ViteDevServer
): Connect.NextHandleFunction {
  const {
    config: { root, logger },
    moduleGraph,
  } = server;
  // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`
  return async function viteTransformMiddleware(req, res, next) {
    // 拉取数据肯定是 GET 请求, 如果不是直接放掉
    // 此外, 如果资源是 ['/', '/favicon.ico'], 也不要通过这里处理, 因为 '/' 就是 index.html, 它已经被上面 indexHtmlMiddleware 处理了
    // favicon.ico 不用多说, 给浏览器用的, 没必要处理
    if (req.method !== "GET" || knownIgnoreList.has(req.url!)) {
      return next();
    }
    let url: string;
    try {
      // 我们知道 vite 为了比较资源的新鲜度, 会给资源的 url 附上一个时间戳 query
      // removeTimestampQuery 这个函数就是把 &t=xxxxxxxxxxxxx 干掉
      // 此外, 我们知道 rollup 的插件机制有虚拟模块的概念, 按照约定如果你用了虚拟模块, 为了防止它被其他插件处理, 需要加上 \0
      // 而一个合法 url 是不能存在 \0 的, 因此 vite 把它转成了 __x00__
      // 所以在 decodeURI 的时候需要把它还原成 \0
      // 一个现实的例子是 /@id/__x00__react/jsx-dev-runtime'
      url = decodeURI(removeTimestampQuery(req.url!)).replace(
        NULL_BYTE_PLACEHOLDER,
        "\0"
      );
    } catch (e) {
      return next(e);
    }
    // 干掉 url 的 query 和 hash
    const withoutQuery = cleanUrl(url);
    try {
      const isSourceMap = withoutQuery.endsWith(".map");
      // since we generate source map references, handle those requests here
      // 首先要分析 sourcemap
      if (isSourceMap) {
        if (getDepsOptimizer(server.config)?.isOptimizedDepUrl(url)) {
          // If the browser is requesting a source map for an optimized dep, it
          // means that the dependency has already been pre-bundled and loaded
          const mapFile = url.startsWith(FS_PREFIX)
            ? fsPathFromId(url)
            : normalizePath(
                ensureVolumeInPath(path.resolve(root, url.slice(1)))
              );
          try {
            const map = await fs.readFile(mapFile, "utf-8");
            return send(req, res, map, "json", {
              headers: server.config.server.headers,
            });
          } catch (e) {
            // Outdated source map request for optimized deps, this isn't an error
            // but part of the normal flow when re-optimizing after missing deps
            // Send back an empty source map so the browser doesn't issue warnings
            const dummySourceMap = {
              version: 3,
              file: mapFile.replace(/\.map$/, ""),
              sources: [],
              sourcesContent: [],
              names: [],
              mappings: ";;;;;;;;;",
            };
            return send(req, res, JSON.stringify(dummySourceMap), "json", {
              cacheControl: "no-cache",
              headers: server.config.server.headers,
            });
          }
        } else {
          const originalUrl = url.replace(/\.map($|\?)/, "$1");
          const map = (await moduleGraph.getModuleByUrl(originalUrl, false))
            ?.transformResult?.map;
          if (map) {
            return send(req, res, JSON.stringify(map), "json", {
              headers: server.config.server.headers,
            });
          } else {
            return next();
          }
        }
      }
      // check if public dir is inside root dir
      // 检查 /public 是否在 / 之内
      // 老实巴交写代码的话, 实在没想到有什么反面例子...
      const publicDir = normalizePath(server.config.publicDir);
      const rootDir = normalizePath(server.config.root);
      if (publicDir.startsWith(rootDir)) {
        const publicPath = `${publicDir.slice(rootDir.length)}/`;
        // warn explicit public paths
        if (url.startsWith(publicPath)) {
          let warning: string;
          if (isImportRequest(url)) {
            const rawUrl = removeImportQuery(url);
            warning =
              "Assets in public cannot be imported from JavaScript.\n" +
              `Instead of ${colors.cyan(
                rawUrl
              )}, put the file in the src directory, and use ${colors.cyan(
                rawUrl.replace(publicPath, "/src/")
              )} instead.`;
          } else {
            warning =
              `files in the public directory are served at the root path.\n` +
              `Instead of ${colors.cyan(url)}, use ${colors.cyan(
                url.replace(publicPath, "/")
              )}.`;
          }
          logger.warn(colors.yellow(warning));
        }
      }
      // 接下来最重要的, 就是拦截客户端请求了哪些类型的资源
      if (
        isJSRequest(url) || // 判断是否请求 js 文件, /\.((j|t)sx?|mjs|vue|marko|svelte|astro)($|\?)/
        isImportRequest(url) || // url 上挂有 import 参数的, vite 会对热更新时请求的文件等挂上 import 参数, /(\?|&)import=?(?:&|$)/
        isCSSRequest(url) || // 判断是否请求 css 文件, `\\.(css|less|sass|scss|styl|stylus|pcss|postcss)($|\\?)`
        isHTMLProxy(url) // url 上挂有 html-proxy 参数的,  /(\?|&)html-proxy\b/
      ) {
        // strip ?import, 干掉 import 参数
        url = removeImportQuery(url);
        // Strip valid id prefix. This is prepended to resolved Ids that are
        // not valid browser import specifiers by the importAnalysis plugin.
        // 如果 url 以 /@id/ 开头，则去掉 /@id/, 上面说了, 这个前缀跟 rollup 插件规范有关
        url = unwrapId(url);
        // for CSS, we need to differentiate between normal CSS requests and
        // imports
        if (
          isCSSRequest(url) &&
          !isDirectRequest(url) &&
          req.headers.accept?.includes("text/css")
        ) {
          url = injectQuery(url, "direct");
        }
        // check if we can return 304 early
        // 找出有没有与 if-none-match 匹配的 etag, 如果有直接返回协商缓存
        const ifNoneMatch = req.headers["if-none-match"];
        if (
          ifNoneMatch &&
          (await moduleGraph.getModuleByUrl(url, false))?.transformResult
            ?.etag === ifNoneMatch
        ) {
          isDebug && debugCache(`[304] ${prettifyUrl(url, root)}`);
          res.statusCode = 304;
          return res.end();
        }
        // resolve, load and transform using the plugin container
        // 对于没有命中协商缓存的, 那就需要进行一波代码编译了
        // 这个我们下面详细说
        const result = await transformRequest(url, server, {
          html: req.headers.accept?.includes("text/html"),
        });
        if (result) {
          const type = isDirectCSSRequest(url) ? "css" : "js";
          // 我们知道 vite 会给 node_moudles 的三方依赖进行预构建
          // 前端在请求三方依赖资源时, 会加上 t={browserHash},
          // 或者资源有 depsCacheDirPrefix 前缀, 就认为是依赖
          const isDep =
            DEP_VERSION_RE.test(url) ||
            getDepsOptimizer(server.config)?.isOptimizedDepUrl(url);
          return send(req, res, result.code, type, {
            etag: result.etag,
            // allow browser to cache npm deps!
            // 如果是依赖的话直接强缓存写死, 下次再请求到这个三方依赖, 直接强缓存返回!
            cacheControl: isDep ? "max-age=31536000,immutable" : "no-cache",
            headers: server.config.server.headers,
            map: result.map,
          });
        }
      }
    } catch (e) {
      if (e?.code === ERR_OPTIMIZE_DEPS_PROCESSING_ERROR) {
        // Skip if response has already been sent
        if (!res.writableEnded) {
          res.statusCode = 504; // status code request timeout
          res.end();
        }
        // This timeout is unexpected
        logger.error(e.message);
        return;
      }
      if (e?.code === ERR_OUTDATED_OPTIMIZED_DEP) {
        // Skip if response has already been sent
        if (!res.writableEnded) {
          res.statusCode = 504; // status code request timeout
          res.end();
        }
        // We don't need to log an error in this case, the request
        // is outdated because new dependencies were discovered and
        // the new pre-bundle dependendencies have changed.
        // A full-page reload has been issued, and these old requests
        // can't be properly fullfilled. This isn't an unexpected
        // error but a normal part of the missing deps discovery flow
        return;
      }
      return next(e);
    }
    next();
  };
}

transformRequest

export function transformRequest(
  url: string,
  server: ViteDevServer,
  options: TransformOptions = {}
): Promise<TransformResult | null> {
  const cacheKey = (options.ssr ? "ssr:" : options.html ? "html:" : "") + url;
  // This module may get invalidated while we are processing it. For example
  // when a full page reload is needed after the re-processing of pre-bundled
  // dependencies when a missing dep is discovered. We save the current time
  // to compare it to the last invalidation performed to know if we should
  // cache the result of the transformation or we should discard it as stale.
  //
  // A module can be invalidated due to:
  // 1. A full reload because of pre-bundling newly discovered deps
  // 2. A full reload after a config change
  // 3. The file that generated the module changed
  // 4. Invalidation for a virtual module
  //
  // For 1 and 2, a new request for this module will be issued after
  // the invalidation as part of the browser reloading the page. For 3 and 4
  // there may not be a new request right away because of HMR handling.
  // In all cases, the next time this module is requested, it should be
  // re-processed.
  //
  // We save the timestamp when we start processing and compare it with the
  // last time this module is invalidated
  const timestamp = Date.now();
  const pending = server._pendingRequests.get(cacheKey);
  if (pending) {
    return server.moduleGraph
      .getModuleByUrl(removeTimestampQuery(url), options.ssr)
      .then((module) => {
        if (!module || pending.timestamp > module.lastInvalidationTimestamp) {
          // The pending request is still valid, we can safely reuse its result
          return pending.request;
        } else {
          // Request 1 for module A     (pending.timestamp)
          // Invalidate module A        (module.lastInvalidationTimestamp)
          // Request 2 for module A     (timestamp)
          // First request has been invalidated, abort it to clear the cache,
          // then perform a new doTransform.
          pending.abort();
          return transformRequest(url, server, options);
        }
      });
  }
  const request = doTransform(url, server, options, timestamp);
  // Avoid clearing the cache of future requests if aborted
  let cleared = false;
  const clearCache = () => {
    if (!cleared) {
      server._pendingRequests.delete(cacheKey);
      cleared = true;
    }
  };
  // Cache the request and clear it once processing is done
  server._pendingRequests.set(cacheKey, {
    request,
    timestamp,
    abort: clearCache,
  });
  request.then(clearCache, clearCache);
  return request;
}

跟静态文件相关的中间件