mirror of
https://github.com/vercel/next.js.git
synced 2026-09-20 02:25:18 +08:00
docs: improve next/image localPatterns error page (#89914)
Align with https://nextjs.org/docs/messages/next-image-unconfigured-host Closes: https://linear.app/vercel/issue/DOC-5850/feedback-image-configuration-it-doesn-t-work-my-pattern-is-defined-as
This commit is contained in:
@@ -4,11 +4,26 @@ title: '`next/image` Un-configured localPatterns'
|
||||
|
||||
## Why This Error Occurred
|
||||
|
||||
One of your pages that leverages the `next/image` component, passed a `src` value that uses a URL that isn't defined in the `images.localPatterns` property in `next.config.js`.
|
||||
One of your pages that leverages the `next/image` component, passed a `src` value that uses a local path that isn't allowed by the `images.localPatterns` configuration in `next.config.js`.
|
||||
|
||||
Each part of the `src` value is matched against your `images.localPatterns` definitions:
|
||||
|
||||
- **Pathname**: The path must be covered by your glob pattern, e.g. `/**` or `/assets/**`. Single `*` matches a single path segment, while double `**` matches any number of path segments.
|
||||
- **Search**: If specified in a pattern, it must match the full search string exactly (including the leading `?`). Globs are not supported for search.
|
||||
|
||||
If any of these differ from the actual `src`, the image will be rejected.
|
||||
|
||||
Common pitfalls that cause this error:
|
||||
|
||||
- A too-narrow pathname pattern (e.g. `/assets/` instead of `/assets/**`).
|
||||
- Setting `search: ''` when your images include query strings like `?v=123` or `?t=timestamp`. An empty string means only URLs **without** query strings are allowed.
|
||||
- Forgetting that pathname patterns are case-sensitive and must match exactly.
|
||||
|
||||
See the [Local Patterns](/docs/pages/api-reference/components/image#localpatterns) reference for details.
|
||||
|
||||
## Possible Ways to Fix It
|
||||
|
||||
Add an entry to `images.localPatterns` array in `next.config.js` with the expected URL pattern. For example:
|
||||
Add the pathname to the `images.localPatterns` config in `next.config.js`:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
@@ -22,9 +37,43 @@ module.exports = {
|
||||
}
|
||||
```
|
||||
|
||||
Omitting the `search` will allow all query strings.
|
||||
### Any search params (default)
|
||||
|
||||
If you want to prevent the query string from matching, you can use the empty string, for example:
|
||||
To allow any search params, omit the `search` key:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
localPatterns: [
|
||||
{
|
||||
pathname: '/api/images/**',
|
||||
// search is omitted, so ?v=123, ?t=456, or no query string are all allowed
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### With specific search params
|
||||
|
||||
To allow only a specific search param value:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
images: {
|
||||
localPatterns: [
|
||||
{
|
||||
pathname: '/assets/**',
|
||||
search: '?v=1',
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### No search params
|
||||
|
||||
To disallow query strings entirely, use an empty string:
|
||||
|
||||
```js filename="next.config.js"
|
||||
module.exports = {
|
||||
|
||||
Reference in New Issue
Block a user