当前位置：首页 > news >正文

Vite 增量构建架构：从缓存命中率到毫秒级热更新的底层设计

news 2026/7/16 17:12:50

Vite 增量构建架构：从缓存命中率到毫秒级热更新的底层设计

一、全量构建的隐性成本：当修改一行代码需要等 30 秒

Vite 在开发模式下以极快的冷启动速度著称，这得益于它基于 ESM 的按需编译策略——只在浏览器请求时才编译对应的模块。然而，当项目规模突破临界点（数百个模块、上千个文件），即使是 Vite 的全量构建也会让开发者感到明显的等待。

生产构建时尤其明显。一次发型变更，全量构建 2 分钟；一个依赖升级，全量构建 5 分钟。这在 CI/CD 流水线中是不可接受的耗时。问题的根源在于：全量构建不区分"未变化的模块"，每次都从头解析、转换、打包所有文件。

增量构建正是解决这一问题的核心设计。通过识别变更文件的影响范围，只重新编译受影响的模块，将构建时间从"模块总数"的量级降低到"变更文件数"的量级。Vite 基于 Rollup 的构建管道天然支持缓存机制，但要真正发挥效力，需要对缓存策略做深度定制。

二、增量构建的核心机制

增量构建效率的三个关键指标：

缓存命中率：已缓存模块在构建中被直接使用的比例
脏模块最小集：一次变更后需要重新编译的模块数量
缓存失效检测开销：判断缓存是否有效所花费的时间（应远小于重新编译的时间）

三、工程实现：构建三层缓存体系

3.1 文件变更检测层

基于 Git 的增量检测，比文件系统 mtime 更可靠：

// cache/FileChangeDetector.ts import { execSync } from 'child_process'; import { createHash } from 'crypto'; import { readFileSync, existsSync } from 'fs'; import { resolve, relative } from 'path'; interface FileSnapshot { path: string; hash: string; mtime: number; size: number; } interface ChangeResult { added: FileSnapshot[]; modified: FileSnapshot[]; deleted: FileSnapshot[]; unchanged: FileSnapshot[]; } class FileChangeDetector { private lastSnapshot: Map<string, FileSnapshot> = new Map(); private readonly projectRoot: string; private readonly ignorePatterns: RegExp[]; constructor(projectRoot: string) { this.projectRoot = resolve(projectRoot); this.ignorePatterns = [ /node_modules/, /\.git\//, /dist\//, /\.cache\//, /\.DS_Store/ ]; } /** * 基于 Git diff 检测变更文件（推荐方式） */ detectChangesFromGit(baseBranch: string = 'HEAD'): ChangeResult { const result: ChangeResult = { added: [], modified: [], deleted: [], unchanged: [] }; try { // 获取变更文件列表 const diffOutput = execSync( `git diff --name-status ${baseBranch} HEAD`, { cwd: this.projectRoot, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 } ); const lines = diffOutput.trim().split('\n'); lines.forEach(line => { if (!line) return; const [status, ...pathParts] = line.split('\t'); const filePath = resolve(this.projectRoot, pathParts.join('\t')); if (this.shouldIgnore(filePath)) return; if (!existsSync(filePath) && status !== 'D') return; const snapshot = this.snapshotFile(filePath); switch (status) { case 'A': result.added.push(snapshot); break; case 'M': result.modified.push(snapshot); break; case 'D': result.deleted.push(snapshot); break; default: // 暂存区变更也视为修改 result.modified.push(snapshot); } }); } catch (error) { console.warn('Git diff 检测失败，降级到全量构建:', error); // 降级：返回空结果，由调用方判断是否触发全量构建 return { added: [], modified: [], deleted: [], unchanged: [] }; } return result; } /** * 基于内容哈希检测变更（备用方式） */ detectChangesByHash( files: string[] ): ChangeResult { const result: ChangeResult = { added: [], modified: [], deleted: [], unchanged: [] }; const currentFiles = new Set(files); // 检测新增和修改的文件 files.forEach(filePath => { if (this.shouldIgnore(filePath)) return; const snapshot = this.snapshotFile(filePath); const previous = this.lastSnapshot.get(filePath); if (!previous) { result.added.push(snapshot); } else if (previous.hash !== snapshot.hash) { result.modified.push(snapshot); } else { result.unchanged.push(snapshot); } }); // 检测删除的文件 this.lastSnapshot.forEach((snapshot, path) => { if (!currentFiles.has(path)) { result.deleted.push(snapshot); } }); // 更新快照 this.lastSnapshot.clear(); [...result.added, ...result.modified, ...result.unchanged].forEach(snapshot => { this.lastSnapshot.set(snapshot.path, snapshot); }); return result; } /** * 为单个文件生成快照 */ private snapshotFile(filePath: string): FileSnapshot { if (!existsSync(filePath)) { return { path: filePath, hash: '', mtime: 0, size: 0 }; } const content = readFileSync(filePath); const stat = require('fs').statSync(filePath); return { path: filePath, hash: createHash('md5').update(content).digest('hex'), mtime: stat.mtimeMs, size: stat.size }; } private shouldIgnore(filePath: string): boolean { const relativePath = relative(this.projectRoot, filePath); return this.ignorePatterns.some(pattern => pattern.test(relativePath)); } }

3.2 依赖图增量更新

根据变更文件，计算需要重新编译的"脏模块"集合：

// cache/DependencyGraph.ts interface ModuleNode { id: string; filePath: string; hash: string; dependencies: Set<string>; // 直接依赖 dependents: Set<string>; // 被依赖（反向关系） buildCache: { transformTime: number; bundleTime: number; lastBuilt: number; } | null; } class DependencyGraph { private nodes: Map<string, ModuleNode> = new Map(); private cacheHits = 0; private cacheMisses = 0; /** * 添加模块节点到依赖图 */ addModule(moduleId: string, filePath: string, dependencies: string[]): void { const node: ModuleNode = this.nodes.get(moduleId) || { id: moduleId, filePath, hash: '', dependencies: new Set(), dependents: new Set(), buildCache: null }; // 更新依赖关系 node.dependencies = new Set(dependencies); // 更新反向依赖 dependencies.forEach(depId => { if (!this.nodes.has(depId)) { this.nodes.set(depId, { id: depId, filePath: '', hash: '', dependencies: new Set(), dependents: new Set(), buildCache: null }); } this.nodes.get(depId)!.dependents.add(moduleId); }); this.nodes.set(moduleId, node); } /** * 计算受变更影响的脏模块集合 * @param changedFiles 变更的文件路径列表 * @returns 需要重新编译的模块 ID 集合 */ getDirtyModules(changedFiles: string[]): Set<string> { const dirty = new Set<string>(); const visited = new Set<string>(); // 第一步：将被直接修改的文件对应的模块标记为脏 changedFiles.forEach(filePath => { this.nodes.forEach((node) => { if (node.filePath === filePath) { dirty.add(node.id); } }); }); // 第二步：BFS 传播 — 所有依赖脏模块的模块也需要重新编译 const queue = [...dirty]; while (queue.length > 0) { const currentId = queue.shift()!; if (visited.has(currentId)) continue; visited.add(currentId); const node = this.nodes.get(currentId); if (!node) continue; // 遍历所有依赖当前模块的模块 node.dependents.forEach(dependentId => { if (!dirty.has(dependentId)) { dirty.add(dependentId); queue.push(dependentId); } }); } return dirty; } /** * 检查模块缓存是否有效 */ isCacheValid(moduleId: string, currentHash: string): boolean { const node = this.nodes.get(moduleId); if (!node || !node.buildCache || !node.hash) { this.cacheMisses++; return false; } // 内容哈希变更 → 缓存失效 if (node.hash !== currentHash) { this.cacheMisses++; return false; } // 检查所有依赖的缓存是否仍然有效 for (const depId of node.dependencies) { const depNode = this.nodes.get(depId); if (!depNode || !depNode.hash || depNode.hash !== this.computeHash(depNode)) { this.cacheMisses++; return false; } } this.cacheHits++; return true; } /** * 获取缓存统计 */ getStats() { return { totalNodes: this.nodes.size, cacheHits: this.cacheHits, cacheMisses: this.cacheMisses, hitRate: this.cacheHits + this.cacheMisses > 0 ? (this.cacheHits / (this.cacheHits + this.cacheMisses) * 100).toFixed(1) + '%' : '0%' }; } private computeHash(node: ModuleNode): string { // 实际项目中应使用文件内容哈希 return node.hash; } }

3.3 Vite 构建缓存插件

将增量构建能力集成到 Vite 插件中：

// plugins/vite-incremental-build.ts import type { Plugin, ResolvedConfig } from 'vite'; import { createHash } from 'crypto'; import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs'; import { resolve, dirname } from 'path'; interface BuildCacheEntry { code: string; map: string | null; hash: string; timestamp: number; dependencies: string[]; } interface DiskCacheManifest { version: number; entries: Record<string, BuildCacheEntry>; } export function incrementalBuildPlugin(): Plugin { let config: ResolvedConfig; let cacheDir: string; let memoryCache: Map<string, BuildCacheEntry> = new Map(); let cacheHits = 0; let cacheTotal = 0; return { name: 'vite:incremental-build', enforce: 'pre', configResolved(resolvedConfig) { config = resolvedConfig; cacheDir = resolve(config.root, 'node_modules/.cache/vite-incremental'); // 确保缓存目录存在 if (!existsSync(cacheDir)) { mkdirSync(cacheDir, { recursive: true }); } // 从磁盘加载持久化缓存 this.loadDiskCache(); }, async transform(code, id) { cacheTotal++; // 跳过 node_modules 中的模块（它们通常很少变更） if (id.includes('node_modules')) { return null; } // 计算模块的内容哈希 const currentHash = createHash('md5').update(code).digest('hex'); // 检查内存缓存 const memCached = memoryCache.get(id); if (memCached && memCached.hash === currentHash) { cacheHits++; return { code: memCached.code, map: memCached.map ? { mappings: memCached.map } : null }; } // 检查磁盘缓存 const diskCached = this.readFromDisk(id); if (diskCached && diskCached.hash === currentHash) { cacheHits++; memoryCache.set(id, diskCached); return { code: diskCached.code, map: diskCached.map ? { mappings: diskCached.map } : null }; } // 缓存未命中，继续正常编译 return null; }, writeBundle(_, bundle) { // 构建完成后，更新缓存 Object.entries(bundle).forEach(([fileName, chunk]) => { if (chunk.type === 'chunk') { const id = resolve(config.root, fileName); const hash = createHash('md5').update(chunk.code).digest('hex'); const entry: BuildCacheEntry = { code: chunk.code, map: typeof chunk.map === 'string' ? chunk.map : null, hash, timestamp: Date.now(), dependencies: Object.keys(chunk.modules || {}) }; memoryCache.set(id, entry); } }); // 将缓存持久化到磁盘 this.saveToDisk(); // 输出缓存统计 const hitRate = ((cacheHits / Math.max(cacheTotal, 1)) * 100).toFixed(1); console.log(`[incremental-build] 缓存命中率: ${hitRate}% (${cacheHits}/${cacheTotal})`); }, buildStart() { // 清理过期缓存（超过 7 天） this.cleanExpiredCache(7 * 24 * 60 * 60 * 1000); } }; }

3.4 缓存驱逐与容量管理

// cache/CacheEviction.ts class CacheEvictionManager { private maxEntries: number; private maxSize: number; // bytes constructor(maxEntries = 5000, maxSizeMB = 500) { this.maxEntries = maxEntries; this.maxSize = maxSizeMB * 1024 * 1024; } /** * LRU 淘汰策略 */ evictByLRU(cache: Map<string, BuildCacheEntry>, targetCount: number): void { if (cache.size <= targetCount) return; const entries = Array.from(cache.entries()) .sort(([, a], [, b]) => a.timestamp - b.timestamp); const toRemove = entries.slice(0, entries.length - targetCount); toRemove.forEach(([key]) => cache.delete(key)); } /** * 按访问频率淘汰 */ evictByFrequency( cache: Map<string, BuildCacheEntry>, accessCounts: Map<string, number>, threshold: number ): void { cache.forEach((_, key) => { const count = accessCounts.get(key) || 0; if (count < threshold) { cache.delete(key); } }); } /** * 定时清理过期缓存 */ cleanExpired(maxAge: number, cacheDir: string): void { const cutoff = Date.now() - maxAge; const manifestPath = resolve(cacheDir, 'manifest.json'); if (!existsSync(manifestPath)) return; try { const manifest: DiskCacheManifest = JSON.parse( readFileSync(manifestPath, 'utf-8') ); const cleaned: DiskCacheManifest = { version: manifest.version, entries: {} }; Object.entries(manifest.entries).forEach(([key, entry]) => { if (entry.timestamp > cutoff) { cleaned.entries[key] = entry; } }); writeFileSync(manifestPath, JSON.stringify(cleaned, null, 2)); console.log( `[cache] 清理过期缓存: ${Object.keys(manifest.entries).length - Object.keys(cleaned.entries).length} 条` ); } catch (error) { console.warn('缓存清理失败:', error); } } }

四、缓存策略的边界与代价

4.1 伪共享与缓存失效爆炸

当一个共享工具函数（如utils/format.ts）被数百个模块依赖时，该函数的任何改动都会导致整个依赖链上的模块缓存全部失效，即"级联失效"。缓解策略包括：将工具函数按功能域拆分，减少单文件的依赖广度；使用sideEffects: false声明，让打包工具安心进行死代码消除。

4.2 磁盘缓存的一致性问题

构建过程中如果发生异常中断，磁盘缓存的写入可能不完整。需要在写入时使用原子操作（先写临时文件，再 rename），并在下次构建时做完整性校验。

function atomicWrite(filePath: string, data: string): void { const tmpPath = filePath + '.tmp.' + Date.now(); try { writeFileSync(tmpPath, data, 'utf-8'); require('fs').renameSync(tmpPath, filePath); } catch (error) { // 清理临时文件 if (existsSync(tmpPath)) { require('fs').unlinkSync(tmpPath); } throw error; } }