refactor: deprecate customResolver in resolve.alias (#21476)

sapphi-red · web-flow · commit 81275c907211 · 2026-02-05T11:50:01.000+09:00
diff --git a/docs/config/shared-options.md b/docs/config/shared-options.md
@@ -92,7 +92,7 @@ Directory to save cache files. Files in this directory are pre-bundled deps or s
 ## resolve.alias
 
 - **Type:**
-  `Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`
+  `Record<string, string> | Array<{ find: string | RegExp, replacement: string }>`
 
 Defines aliases used to replace values in `import` or `require` statements. This works similar to [`@rollup/plugin-alias`](https://github.com/rollup/plugins/tree/master/packages/alias).
 
@@ -119,7 +119,7 @@ resolve: {
 }
 ```
 
-### Array Format (`Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`)
+### Array Format (`Array<{ find: string | RegExp, replacement: string }>`)
 
 The Array format allows specifying aliases as objects, which can be useful for complex key/value pairs.
 
@@ -138,8 +138,6 @@ When `find` is a regular expression, the `replacement` can use [replacement patt
 { find:/^(.*)\.js$/, replacement: '$1.alias' }
 ```
 
-`customResolver` option can be used to provide separate module resolution for an individual alias.
-
 ## resolve.dedupe
 
 - **Type:** `string[]`
diff --git a/docs/guide/migration.md b/docs/guide/migration.md
@@ -328,6 +328,7 @@ The following options are deprecated and will be removed in the future:
 - `worker.rollupOptions`: renamed to `worker.rolldownOptions`
 - `build.commonjsOptions`: it is now no-op
 - `build.dynamicImportVarsOptions.warnOnError`: it is now no-op
+- `resolve.alias[].customResolver`: Use a custom plugin with `resolveId` hook instead
 
 ## General Changes [<Badge text="NRV" type="warning" />](#migration-from-v7)
 
diff --git a/packages/vite/src/node/config.ts b/packages/vite/src/node/config.ts
@@ -1137,6 +1137,15 @@ function resolveResolveOptions(
       ),
     )
   }
+  if (alias.some((a) => a.customResolver)) {
+    logger.warn(
+      colors.yellow(
+        `\`resolve.alias\` contains an alias with \`customResolver\` option. ` +
+          `This is deprecated and will be removed in Vite 9. ` +
+          `Please use a custom plugin with a resolveId hook instead.`,
+      ),
+    )
+  }
 
   return resolveEnvironmentResolveOptions(
     resolve,
diff --git a/packages/vite/src/types/alias.d.ts b/packages/vite/src/types/alias.d.ts
@@ -36,6 +36,7 @@ export interface Alias {
    * Instructs the plugin to use an alternative resolving algorithm,
    * rather than the Rollup's resolver.
    * @default null
+   * @deprecated Use a custom plugin with resolveId hook instead
    */
   customResolver?: ResolverFunction | ResolverObject | null
 }

Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@ export interface Alias {`
`36`	`36`	`* Instructs the plugin to use an alternative resolving algorithm,`
`37`	`37`	`* rather than the Rollup's resolver.`
`38`	`38`	`* @default null`
	`39`	`+ * @deprecated Use a custom plugin with resolveId hook instead`
`39`	`40`	`*/`
`40`	`41`	`customResolver?: ResolverFunction \| ResolverObject \| null`
`41`	`42`	`}`