Vite dev 启动 9 秒：从代码排查到磁盘介质的完整定位

一、结论速览

二、现象与根因

现象：

• 执行 npm run dev 后，浏览器打开页面 loading 时间 10 秒以上；
• 首屏 143 个请求（进入业务页后增至 170+），大量请求长时间处于 pending；
• 接口请求本身不慢，慢在静态资源 / 模块加载阶段；
• 代码未发生变更（仓库最后一次提交在三周前），可排除「新代码引入」。

根因：项目目录位于一块外接 USB 机械硬盘上。diskutil 确认介质类型（设备名已脱敏）：

$ diskutil info <外接盘>
   Protocol:                  USB
   Device Location:           External
   Solid State:               No          ← 机械硬盘（旋转盘片）

Vite 开发服务器在启动与提供模块时，需要读取成千上万个小文件（Vite 自身、插件、node_modules 里的包元数据与源码；本项目 node_modules 中 <200 KB 的小文件共 24,524 个）。这类随机小文件读在机械盘上的单次延迟比 SSD 高两个数量级以上，于是 I/O 等待直接变成了用户看到的「启动慢 / 请求 pending」。

三、定位过程

排查遵循「先排除代码 → 分段计时 → 采样剖析 → 冷热对照 → 硬件确认」的顺序。这套流程可复用于任何「前端变慢」的问题。

3.1 先排除代码侧与显性配置

3.2 分段计时：耗时全部集中在 createServer

用 Vite 的 JS API 把启动拆成四段（脚本见仓库 vite_startup_timing.mjs）：

import { createServer } from 'vite'
const t = () => performance.now()
const a = t(); const server = await createServer({ root: process.cwd() })
const b = t(); await server.listen()
const c = t(); await (await fetch('http://<dev-host>:51999/')).text()
const d = t(); await server.transformRequest('/src/main.js')
const e = t()
console.log({ createServer: b-a, listen: c-b, firstRequest: d-c, transform: e-d })

* 此行是 JS API、服务已就绪条件下的读数；§3.5 浏览器实测的 GET / 4009 ms 是冷盘 + 首次整页加载场景，两者条件不同，并不矛盾。

结论：9 秒多的耗时几乎全部在 createServer 阶段，且同样的输入、同样的缓存，冷热相差 41 倍——说明它不是在「算」，而是在「等 I/O」。

3.3 CPU Profile：耗时函数全是同步文件 I/O

对慢启动采样 .cpuprofile（Node --cpu-prof，采样间隔 500 µs），按命中次数排序：

readFileUtf8      (native)                        ← 最大头
(idle)            (native)
readPackageJSON   (native)                        ← Node 的 ESM/CJS 解析器逐个读 package.json
read              (native)
wrapSafe          node:internal/modules/cjs/loader
dlopen            (native)                        ← 加载原生模块
statSync          node:fs
realpathSync      node:fs
getPackageScopeConfig (native)

没有任何计算密集的函数——全部是 read / stat / realpath / dlopen 这类纯文件系统调用。与 §3.2 的判断互相印证。

3.4 小文件随机读基准

对 node_modules 中 <200 KB 的小文件（共 24,524 个）均匀抽样 2000 个逐一完整读取（脚本见仓库 bench_small_files.mjs），两次采样：

第 1 次：读取 2000 个文件（共 6.4 MB，失败 0）  总耗时 4.04s  平均 2.02 ms/文件
第 2 次：读取 2000 个文件（共 6.4 MB，失败 0）  总耗时 5.05s  平均 2.52 ms/文件

即在部分页缓存（排查过程中已多次读过 node_modules）的乐观条件下，也有 2.0 – 2.5 ms/文件，折合有效随机读仅约 400–500 文件/秒。随后在更冷的状态下复测，得到 6.17 ms/文件——真实冷盘只会更差。真正稳健的证据仍是 §3.2 的 41× 冷热比。

机械盘的单次 I/O 延迟可以用教科书参数直接算出来，不需要引用任何评测：7200 RPM 盘片旋转一周 = 60 s ÷ 7200 ≈ 8.33 ms，平均等待半圈 ≈ 4.17 ms；磁头平均寻道 ≈ 9 ms；合计单次随机 I/O ≈ 13 ms 量级，即上限约 70–150 IOPS。而 SSD 无机械动作，读延迟 < 0.1 ms，SATA SSD 4K 随机 IOPS 通常在数万级，NVMe 更高——两个数量级的差距。

3.5 浏览器侧请求瀑布

用 Playwright 真实浏览器加载 dev 页面，记录全部请求（脚本见仓库 waterfall.mjs）：

=== 结果 ===
  页面加载时间(含额外等待): 19.3s
  请求总数: 143   已完成: 143   仍 pending: 0

=== 最慢的请求 ===
    4009ms  200  /
     137ms  200  /@vite/client
     132ms  200  /src/main.js
      61ms  200  /node_modules/.vite/deps/chunk-*.js
      55ms  200  /node_modules/.vite/deps/element-plus.js
      52ms  200  /src/utils/theme.js

关键观察：单个模块请求都在 50–140 ms 量级（SSD 上本该是 1–5 ms），而第一个 GET / 就花了 4009 ms——服务端要先从冷盘把整条模块链路读起来。每个请求都在等磁盘，整体表现就是「一堆请求卡在 pending」。

3.6 Spotlight 索引叠加

$ mdutil -s <外接卷>
Indexing enabled.

该卷的 Spotlight 索引处于开启状态。mds / mdworker 会在后台持续扫描文件系统元数据，在机械盘上与开发工具链争抢磁头——这是叠加在根因之上的放大器。

四、机理：为什么机械盘会放大 Vite 的耗时

4.1 Vite dev 的性能模型本身就是 I/O 密集的

Vite 开发模式刻意不做打包：依赖浏览器原生 ESM，按需转换、按需返回每个模块。这是它启动快的原因，但也意味着页面加载路径上每一个模块都要经过一次服务端文件读取 + 转换 + 一次 HTTP 往返。

本次实测：dev 首屏 143 个请求，其中 112 个是 src 源码模块、22 个是预打包依赖。在 SSD 上这是毫秒级的开销，在机械盘上每个请求要等几毫秒到十几毫秒的寻道，143 个请求串起来就是十几秒。

4.2 模块解析的隐藏文件系统开销

官方给过一个具体例子——解析隐式扩展名的 import，最坏情况要逐次探测：

一个常见误区要澄清：本项目配置的 extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue'] 看起来是「加长」，实际上 Vite 默认值本来就是 7 项（含 .mts），项目只是把 .mts 换成了 .vue，数量与默认相同，最坏探测次数也相同。真正的要点是：隐式扩展名导入天然带多次 stat 探测（完全未命中时，含无扩展名探测在内最多 8 次），在 SSD 上每次探测不足 0.1 ms 可以忽略，在机械盘上每次都要付一次寻道代价。显式写全扩展名、收敛用不到的项，收益随盘速放大。

4.3 Barrel file（桶文件）放大效应

官方专门有一节讲这个问题：

本项目有两处典型的桶文件式全量引入：

实测实际用量：模板中只用到 55 个 element-plus 组件、29 个图标。

4.4 机械盘与 SSD 的数量级差

如 §3.4 所算：机械盘读一个文件要付「寻道 ≈9 ms + 等半圈 ≈4.17 ms」，SSD 无机械动作、延迟 < 0.1 ms，且支持深度并发队列。这意味着：在 SSD 上「并行读 1000 个小文件」是并行的；在机械盘上本质是串行的——磁头同一时刻只能在一个位置。开发工具链（node_modules 解析、模块图构建、IDE 索引、git status）恰恰是「海量小文件随机读」的典型负载，因此受机械盘惩罚最重。

4.5 预打包依赖同样要读盘

Vite 的依赖预构建缓存位于 node_modules/.vite/deps，本项目为 25 MB / 60 个文件：

2528.1 KB  echarts.js
2063.1 KB  element-plus.js
 850.5 KB  xlsx.js
 414.7 KB  chunk-*.js
 410.7 KB  vue-quill
 397.9 KB  vuedraggable
 289.0 KB  @vueuse/core
 184.1 KB  js-beautify

这些文件在 dev 下由浏览器直接请求（官方说明：预打包依赖使用 max-age=31536000, immutable 强缓存，命中后不再回源）。但首次加载仍必须从盘上读出这 25 MB。官方文档同时说明：依赖预构建只在开发模式应用，生产构建走的是另一套（Rollup）流程——这正是「dev 慢、生产不慢」的机制来源之一。

五、影响范围：开发严重，生产不受影响

5.1 开发环境——严重影响

Vite dev server 的全部转换都在项目目录上进行，每一次页面加载、每一次 HMR 都要读这块盘。受影响的日常操作：npm run dev 启动、页面刷新、HMR 响应、首次进入某个路由（懒加载 chunk 要现读现转）。

5.2 本地构建——轻微

$ npm run build:prod
build #1: real 21.79
build #2: real 15.37

15–22 秒，是一次性成本（每次发版一次），远低于任何 CI 超时阈值。SSD 上预计可降到 8–12 秒，但收益有限，不构成问题。

5.3 Docker 镜像构建——基本不受影响

项目的构建链是 Docker 化的，这一点很关键：

# 多阶段构建（示意）
FROM node:20-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build:prod && chmod -R a+r /app/dist

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 8080

三个原因使它与这块机械盘基本解耦：

1. .dockerignore 已正确排除大目录（node_modules / dist / .git），构建上下文因此只有约 29 MB（项目 349 MB − node_modules 302 MB − .git 18 MB）。反过来，如果 .dockerignore 缺失或写错，Docker 会把 302 MB / 24,524 个文件送进 daemon，那才会真正拖垮构建；
2. npm ci 与 npm run build:prod 在容器内执行，读写的是 Docker Desktop 虚拟机的磁盘镜像（位于内置 SSD），不是外接卷；
3. 只有 COPY . . 这一步读本机源码（约 29 MB），可忽略。

5.4 生产运行——不受影响

docker run -d --name my-web -p 8080:8080 \
  -v ${LOG_DIR}:/var/log/nginx \
  ${IMAGE}:latest

运行时唯一挂载的是宿主机日志目录；前端静态文件是 COPY --from=builder /app/dist 打进镜像的，由容器内 nginx 提供。整个服务链路不读外接卷。因此对最终用户而言：加载速度只取决于构建产物体积与部署机到用户的网络，与开发机磁盘没有任何关系——本次问题不会表现为线上变慢，不需要为此回滚或加急修复。

5.5 其他受影响的日常操作

• npm install / npm ci：解压上万个包文件，机械盘上耗时成倍增加；
• git status / git diff：.git 也在该盘上；
• IDE（VS Code 等）的项目索引与语义分析；
• Spotlight 后台索引本身的持续 I/O 占用。

pnpm 用户在机械盘上遇到 install 长期卡在 reused/added 阶段的同类案例，可参考掘金《当 pnpm 遇上机械硬盘》——把 store 迁到 SSD 后恢复流畅，与本文结论互为印证。

六、修复方案与取舍

方案 A：把项目移到内置 SSD——唯一根治

依据：§3.2 的 41× 冷热差与 §3.4 的介质对比都指向存储介质本身，任何代码层优化都只能缓解、不能根治。内置 NVMe SSD 容量 228 GB、已用 91%、可用约 16 GB；项目总占用 349 MB，放得下，但需评估余量。做法：整仓库迁移（rsync 或重新 git clone 后 npm ci），迁移后重跑仓库里的 T1 / T3 验证。

方案 B：别让 Spotlight 扫这块盘

# 1) 仅关闭该卷索引（推荐，可逆）
sudo mdutil -i off <外接卷>

# 2) 图形化等价做法：系统设置 → Siri 与聚焦 → 聚焦 → 隐私，把该卷加入排除列表

# 3) 卷根目录放 .metadata_never_index（设备级、无需 sudo）
#    ⚠️ 未经本文实测；社区有较新 macOS 上失效的反馈。
#    验证方法：放置后执行 `mdutil -s <卷>`，若仍显示 Indexing enabled 即无效。

代价：该盘上的文件将无法被 Spotlight 搜索到。若盘上还存有需要检索的资料，先确认再执行。

方案 C：让 Vite 少读文件（不迁移也能改善）

C1. 预热高频文件——官方机制 server.warmup：

server: {
  warmup: {
    clientFiles: ['./src/main.js', './src/layout/**/*.vue', './src/components/Editor/index.vue'],
  },
}

官方提醒只应预热频繁使用的文件，以免给启动增加负担；使用 --open / server.open 也会自动预热应用入口。C2. 显式写导入扩展名 / 收敛 resolve.extensions——注意默认值本就是 7 项，收益来自减少隐式导入的 stat 探测次数，且随盘速放大（SSD 上收益很小）。C3. 消除桶文件全量引入——见方案 D。

方案 D：包体治理（减少首屏字节数与文件数）

这解决的是另一个独立问题（首屏体积），但在机械盘上它同时是放大器（§4.3）。三件事，按性价比排序：

另有一项独立于本次问题的观察：echarts 在 9 个文件中被 import * as echarts 全量引入，生成了一个 1012 KB（gzip 335 KB）的 chunk，可通过 echarts/core 按需引入缩减。现状基线（供改造后对照）：dist 入口 JS 1722.5 KB / gzip 561 KB，同目录 CSS 455.3 KB / gzip 64.9 KB，echarts chunk 1012.0 KB / gzip 334.7 KB。

方案取舍建议

七、在你的项目上复现

以下用例脚本均已在 opc-dev-io-bench 开源，可在任何项目上复现同样的定位流程：

T2 判定标准：< 0.2 ms/文件为 SSD 正常；0.5 – 2 ms 为慢介质或部分缓存；> 2 ms/文件即为机械盘，必然拖慢前端工具链。T1 判读：热缓存 createServer 通常 0.2–3 s；冷缓存达 8–20 s 且冷热差超 10×，即复现本问题。

T6 生产解耦验证（三条命令确认生产链路与该盘无关）：

# 1) 确认构建上下文不含大目录（应只列出源码，不含 node_modules）
docker build --no-cache --progress=plain -t iotest . 2>&1 | grep -i "transferring context"

# 2) 确认镜像内静态文件来自构建阶段，而非本机挂载
docker run --rm --entrypoint sh iotest -c "ls /usr/share/nginx/html | head"

# 3) 确认部署链路文件（Dockerfile / nginx.conf / 部署脚本）中没有指向外接卷的路径
grep -rn "<外接卷挂载路径>" Dockerfile nginx.conf deploy.sh
# 预期：无输出

迁移验收的预期对照：createServer 冷缓存 9430 ms → < 1500 ms，热缓存 228 ms → 200–400 ms，小文件随机读 → < 0.2 ms/文件，首屏总时长 10 s+ → 1–3 s。

八、写在最后

这次排查最大的收获不是「换个盘」这个结论，而是流程本身：先排除代码侧、再分段计时锁定阶段、用 CPU Profile 区分「算」与「等」、用冷热对照证明 I/O 依赖、最后才下介质结论。每一步都有可复现的测量，反直觉的结论才立得住。遇到「变慢」，先用测量逼近根因，再动手优化——顺序反过来，大概率是在给错误的瓶颈写优化代码。