feat(matcher): hint at params: {} workaround in discarded params warning (#2689)

posva · shanliuling · web-flow · commit c2b13c616057 · 2026-04-22T15:20:41.000+02:00
Close #1617 Co-authored-by: shanliuling <1362913430@qq.com>
diff --git a/packages/router/__tests__/warnings.spec.ts b/packages/router/__tests__/warnings.spec.ts
@@ -312,5 +312,44 @@ describe('warnings', () => {
     expect('invalid param(s) "no", "foo" ').toHaveBeenWarned()
     // from the previous location
     expect('"one"').not.toHaveBeenWarned()
+    // explicit params (not inherited) should not trigger the workaround hint
+    expect('catch-all route with a named redirect').not.toHaveBeenWarned()
+  })
+
+  it('hints at the `params: {}` workaround when discarded params are inherited', () => {
+    const record = {
+      path: '/a',
+      name: 'a',
+      components: {},
+    }
+    const matcher = createRouterMatcher([record], {})
+    matcher.resolve(
+      { name: 'a', params: { pathMatch: 'unknown' } },
+      {
+        path: '/unknown',
+        name: undefined,
+        params: { pathMatch: 'unknown' },
+        matched: [] as any,
+        meta: {},
+      }
+    )
+    expect('Discarded invalid param(s)').toHaveBeenWarned()
+    expect('catch-all route with a named redirect').toHaveBeenWarned()
+  })
+
+  it('does not warn for a catch-all redirect using the `params: {}` workaround', async () => {
+    const history = createMemoryHistory()
+    const router = createRouter({
+      history,
+      routes: [
+        { path: '/', name: 'HOME', component },
+        {
+          path: '/:pathMatch(.*)*',
+          redirect: { name: 'HOME', params: {} },
+        },
+      ],
+    })
+    await router.push('/anything')
+    expect('Discarded invalid param(s)').not.toHaveBeenWarned()
   })
 })
diff --git a/packages/router/src/matcher/index.ts b/packages/router/src/matcher/index.ts
@@ -265,10 +265,20 @@ export function createRouterMatcher(
         ).filter(paramName => !matcher!.keys.find(k => k.name === paramName))
 
         if (invalidParams.length) {
+          // when the invalid params are inherited from the current location
+          // (e.g. `pathMatch` from a catch-all redirecting to a named route),
+          // suggest the `params: {}` workaround
+          const isInherited =
+            !matcher!.keys.length &&
+            invalidParams.some(name => name in currentLocation.params)
           warn(
             `Discarded invalid param(s) "${invalidParams.join(
               '", "'
-            )}" when navigating. See https://github.com/vuejs/router/blob/main/packages/router/CHANGELOG.md#414-2022-08-22 for more details.`
+            )}" when navigating.` +
+              (isInherited
+                ? ` If you are using a catch-all route with a named redirect, pass an empty \`params\` object: \`redirect: { name: '...', params: {} }\`.`
+                : '') +
+              ` See https://github.com/vuejs/router/blob/main/packages/router/CHANGELOG.md#414-2022-08-22 for more details.`
           )
         }
       }
