fix(virtual-url-plugin): sanitize paths for Windows compatibility (#20424)

xiaoxiaojx · web-flow · commit e06423b3f503 · 2026-02-08T16:59:18.000+03:00
diff --git a/.changeset/fix-virtual-url-plugin-windows-compatibility.md b/.changeset/fix-virtual-url-plugin-windows-compatibility.md
@@ -0,0 +1,5 @@
+---
+"webpack": patch
+---
+
+Fix VirtualUrlPlugin Windows compatibility by sanitizing cache keys and filenames. Cache keys now use `toSafePath` to replace colons (`:`) with double underscores (`__`) and sanitize other invalid characters, ensuring compatibility with Windows filesystem restrictions.
diff --git a/lib/schemes/VirtualUrlPlugin.js b/lib/schemes/VirtualUrlPlugin.js
@@ -126,6 +126,27 @@ class VirtualUrlPlugin {
 		compiler.hooks.compilation.tap(
 			PLUGIN_NAME,
 			(compilation, { normalModuleFactory }) => {
+				compilation.hooks.assetPath.tap(
+					{ name: PLUGIN_NAME, before: "TemplatedPathPlugin" },
+					(path, data) => {
+						if (data.filename && this.modules[data.filename]) {
+							/**
+							 * @param {string} str path
+							 * @returns {string} safe path
+							 */
+							const toSafePath = (str) =>
+								`__${str
+									.replace(/:/g, "__")
+									.replace(/^[^a-z0-9]+|[^a-z0-9]+$/gi, "")
+									.replace(/[^a-z0-9._-]+/gi, "_")}`;
+
+							// filename: virtual:logo.svg -> __virtual__logo.svg
+							data.filename = toSafePath(data.filename);
+						}
+						return path;
+					}
+				);
+
 				normalModuleFactory.hooks.resolveForScheme
 					.for(scheme)
 					.tap(PLUGIN_NAME, (resourceData) => {
diff --git a/test/configCases/plugins/virtual-url-plugin/index.js b/test/configCases/plugins/virtual-url-plugin/index.js
@@ -40,6 +40,9 @@ it("should correctly load virtual modules with custom loader.", (done) => {
 
 it("should correctly load virtual modules with the asset/resource type.", (done) => {
     const fs = __non_webpack_require__("fs");
+    // windows doesn't allow : in file names
+    expect(Hammer).not.toContain(":");
+    expect(Hammer).toContain("__");
     expect(fs.readFileSync(__dirname + "/" + Hammer, "utf-8")).toContain("</svg>");
     done();
 });

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"webpack": patch
 +---
++
 +Fix VirtualUrlPlugin Windows compatibility by sanitizing cache keys and filenames. Cache keys now use `toSafePath` to replace colons (`:`) with double underscores (`__`) and sanitize other invalid characters, ensuring compatibility with Windows filesystem restrictions.