fix(optimize-deps): ensure consistent browserHash between in-memory and persisted metadata

When the dev server restarts mid–asset waterfall and loads cached
`_metadata.json`, inconsistent `browserHash` values can cause duplicate
instances of the same dependency to be loaded (e.g. multiple React copies).

This patch sets the `browserHash` eagerly in memory before resolving
`scanProcessing`, ensuring both the in-memory metadata and the persisted
metadata use the same value.

Author: infiton

packages/vite/src/node/optimizer/index.ts

@@ -1330,11 +1330,11 @@ function getDepHash(environment: Environment): {
   }
 }
 
-function getOptimizedBrowserHash(
+export function getOptimizedBrowserHash(
   hash: string,
   deps: Record<string, string>,
   timestamp = '',
-) {
+): string {
   return getHash(hash + JSON.stringify(deps) + timestamp)
 }
 

packages/vite/src/node/optimizer/optimizer.ts

@@ -15,6 +15,7 @@ import {
   depsLogString,
   discoverProjectDependencies,
   extractExportsData,
+  getOptimizedBrowserHash,
   getOptimizedDepPath,
   initDepsOptimizerMetadata,
   loadCachedDepOptimizationMetadata,
@@ -237,6 +238,20 @@ export function createDepsOptimizer(
               const knownDeps = prepareKnownDeps()
               startNextDiscoveredBatch()
 
+              // Ensure consistent browserHash between in-memory and persisted metadata.
+              // By setting it eagerly here (before scanProcessing resolves), both the
+              // current server and any subsequent server loading _metadata.json will
+              // produce the same browserHash for these deps, avoiding mismatches during
+              // mid-load restarts.
+              metadata.browserHash = getOptimizedBrowserHash(
+                metadata.hash,
+                depsFromOptimizedDepInfo(knownDeps),
+              )
+
+              for (const dep of Object.keys(metadata.discovered)) {
+                metadata.discovered[dep].browserHash = metadata.browserHash
+              }
+
               // For dev, we run the scanner and the first optimization
               // run on the background
               optimizationResult = runOptimizeDeps(environment, knownDeps)

packages/vite/src/node/plugins/importAnalysis.ts

@@ -331,6 +331,8 @@ export function importAnalysisPlugin(config: ResolvedConfig): Plugin {
           depsOptimizer &&
           moduleListContains(depsOptimizer.options.exclude, url)
         ) {
+          // Wait for scanning to complete to ensure stable browserHash and metadata
+          // This prevents inconsistent hashes between in-memory and persisted metadata
           await depsOptimizer.scanProcessing
 
           // if the dependency encountered in the optimized file was excluded from the optimization

packages/vite/src/node/plugins/resolve.ts

@@ -214,7 +214,11 @@ export function resolvePlugin(
           }
         }
 
-        let res: string | PartialResolvedId | undefined
+        let res:
+          | string
+          | PartialResolvedId
+          | undefined
+          | Promise<PartialResolvedId | undefined>
 
         // resolve pre-bundled deps requests, these could be resolved by
         // tryFileResolve or /fs/ resolution but these files may not yet
@@ -233,7 +237,7 @@ export function resolvePlugin(
           // always return here even if res doesn't exist since /@fs/ is explicit
           // if the file doesn't exist it should be a 404.
           debug?.(`[@fs] ${colors.cyan(id)} -> ${colors.dim(res)}`)
-          return ensureVersionQuery(res, id, options, depsOptimizer)
+          return await ensureVersionQuery(res, id, options, depsOptimizer)
         }
 
         // URL
@@ -246,7 +250,7 @@ export function resolvePlugin(
           const fsPath = path.resolve(root, id.slice(1))
           if ((res = tryFsResolve(fsPath, options))) {
             debug?.(`[url] ${colors.cyan(id)} -> ${colors.dim(res)}`)
-            return ensureVersionQuery(res, id, options, depsOptimizer)
+            return await ensureVersionQuery(res, id, options, depsOptimizer)
           }
         }
 
@@ -268,6 +272,9 @@ export function resolvePlugin(
             // Optimized files could not yet exist in disk, resolve to the full path
             // Inject the current browserHash version if the path doesn't have one
             if (!options.isBuild && !DEP_VERSION_RE.test(normalizedFsPath)) {
+              // Wait for scanning to complete to ensure stable browserHash
+              // This prevents inconsistent hashes between in-memory and persisted metadata
+              await depsOptimizer.scanProcessing
               const browserHash = optimizedDepInfoFromFile(
                 depsOptimizer.metadata,
                 normalizedFsPath,
@@ -287,7 +294,7 @@ export function resolvePlugin(
           }
 
           if ((res = tryFsResolve(fsPath, options))) {
-            res = ensureVersionQuery(res, id, options, depsOptimizer)
+            res = await ensureVersionQuery(res, id, options, depsOptimizer)
             debug?.(`[relative] ${colors.cyan(id)} -> ${colors.dim(res)}`)
 
             if (!options.idOnly && !options.scan && options.isBuild) {
@@ -318,7 +325,7 @@ export function resolvePlugin(
           const fsPath = path.resolve(basedir, id)
           if ((res = tryFsResolve(fsPath, options))) {
             debug?.(`[drive-relative] ${colors.cyan(id)} -> ${colors.dim(res)}`)
-            return ensureVersionQuery(res, id, options, depsOptimizer)
+            return await ensureVersionQuery(res, id, options, depsOptimizer)
           }
         }
 
@@ -328,7 +335,7 @@ export function resolvePlugin(
           (res = tryFsResolve(id, options))
         ) {
           debug?.(`[fs] ${colors.cyan(id)} -> ${colors.dim(res)}`)
-          return ensureVersionQuery(res, id, options, depsOptimizer)
+          return await ensureVersionQuery(res, id, options, depsOptimizer)
         }
 
         // external
@@ -378,15 +385,12 @@ export function resolvePlugin(
             return res
           }
 
-          if (
-            (res = tryNodeResolve(
-              id,
-              importer,
-              options,
-              depsOptimizer,
-              external,
-            ))
-          ) {
+          res = tryNodeResolve(id, importer, options, depsOptimizer, external)
+          if (res) {
+            // Handle both sync and async returns
+            if (res instanceof Promise) {
+              return await res
+            }
             return res
           }
 
@@ -528,18 +532,21 @@ function resolveSubpathImports(
   return importsPath + postfix
 }
 
-function ensureVersionQuery(
+async function ensureVersionQuery(
   resolved: string,
   id: string,
   options: InternalResolveOptions,
   depsOptimizer?: DepsOptimizer,
-): string {
+): Promise<string> {
   if (
     !options.isBuild &&
     !options.scan &&
     depsOptimizer &&
     !(resolved === normalizedClientEntry || resolved === normalizedEnvEntry)
   ) {
+    // Wait for scanning to complete to ensure stable browserHash
+    // This prevents inconsistent hashes between in-memory and persisted metadata
+    await depsOptimizer.scanProcessing
     // Ensure that direct imports of node_modules have the same version query
     // as if they would have been imported through a bare import
     // Use the original id to do the check as the resolved id may be the real
@@ -699,7 +706,7 @@ export function tryNodeResolve(
   options: InternalResolveOptions,
   depsOptimizer?: DepsOptimizer,
   externalize?: boolean,
-): PartialResolvedId | undefined {
+): PartialResolvedId | undefined | Promise<PartialResolvedId | undefined> {
   const { root, dedupe, isBuild, preserveSymlinks, packageCache } = options
 
   // check for deep import, e.g. "my-lib/foo"
@@ -833,6 +840,20 @@ export function tryNodeResolve(
     // can cache it without re-validation, but only do so for known js types.
     // otherwise we may introduce duplicated modules for externalized files
     // from pre-bundled deps.
+
+    // If we need to access browserHash, we must wait for scanning to complete
+    // to ensure stable browserHash and prevent inconsistent hashes between
+    // in-memory and persisted metadata
+    if (depsOptimizer.scanProcessing) {
+      return depsOptimizer.scanProcessing.then(() => {
+        const versionHash = depsOptimizer.metadata.browserHash
+        if (versionHash && isJsType && resolved) {
+          resolved = injectQuery(resolved, `v=${versionHash}`)
+        }
+        return processResult({ id: resolved! })
+      })
+    }
+
     const versionHash = depsOptimizer.metadata.browserHash
     if (versionHash && isJsType) {
       resolved = injectQuery(resolved, `v=${versionHash}`)
@@ -854,8 +875,8 @@ export async function tryOptimizedResolve(
   preserveSymlinks?: boolean,
   packageCache?: PackageCache,
 ): Promise<string | undefined> {
-  // TODO: we need to wait until scanning is done here as this function
-  // is used in the preAliasPlugin to decide if an aliased dep is optimized,
+  // Wait for scanning to complete to ensure stable browserHash and metadata
+  // This function is used in the preAliasPlugin to decide if an aliased dep is optimized,
   // and avoid replacing the bare import with the resolved path.
   // We should be able to remove this in the future
   await depsOptimizer.scanProcessing
@@ -1116,12 +1137,14 @@ function tryResolveBrowserMapping(
     if (browserMappedPath) {
       if (
         (res = bareImportRE.test(browserMappedPath)
-          ? tryNodeResolve(
-              browserMappedPath,
-              importer,
-              options,
-              undefined,
-              undefined,
+          ? (
+              tryNodeResolve(
+                browserMappedPath,
+                importer,
+                options,
+                undefined,
+                undefined,
+              ) as PartialResolvedId | undefined
             )?.id
           : tryFsResolve(path.join(pkg.dir, browserMappedPath), options))
       ) {

playground/optimize-deps/__tests__/optimize-deps.spec.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from 'vitest'
 import {
+  browser,
   browserErrors,
   browserLogs,
   getColor,
@@ -8,6 +9,7 @@ import {
   page,
   readDepOptimizationMetadata,
   serverLogs,
+  viteServer,
   viteTestUrl,
 } from '~utils'
 
@@ -354,3 +356,32 @@ test('dependency with external sub-dependencies', async () => {
     .poll(() => page.textContent('.dep-cjs-with-external-deps-node-builtin'))
     .toBe('foo bar')
 })
+
+test.runIf(isServe)(
+  'the metadata written by the dep optimizer should match the metadata in memory',
+  async () => {
+    await viteServer.waitForRequestsIdle()
+    const metadata = readDepOptimizationMetadata()
+
+    let page = await browser.newPage()
+    const response = page.waitForResponse(/\/cjs\.js/)
+    await page.goto(viteTestUrl)
+
+    const content = await (await response).text()
+    const reactBrowserHash = content.match(
+      /from "\/node_modules\/\.vite\/deps\/react\.js\?v=([^"&]*)"/,
+    )?.[1]
+    expect(reactBrowserHash).toBe(metadata.browserHash)
+
+    await viteServer.restart()
+
+    page = await browser.newPage()
+    const responseAfterRestart = page.waitForResponse(/cjs\.js/)
+    await page.goto(viteTestUrl)
+    const contentAfterRestart = await (await responseAfterRestart).text()
+    const reactBrowserHashAfterRestart = contentAfterRestart.match(
+      /from "\/node_modules\/\.vite\/deps\/react\.js\?v=([^"&]*)"/,
+    )?.[1]
+    expect(reactBrowserHashAfterRestart).toBe(metadata.browserHash)
+  },
+)