Astro 远程图片域名白名单配置

在 Astro 项目里使用 <Image /> 引用远程图片时，如果构建阶段提示远程图片不被允许，通常不是图片地址本身失效，而是 Astro 的图片优化默认没有放行这个外部域名。

解决思路很简单：在 astro.config.mjs 里明确声明允许访问的远程图片域名。这样可以继续保留 Astro 的图片优化能力，也能避免把真实业务图片域名散落在页面组件里。

推荐配置

打开项目根目录的 astro.config.mjs，在 defineConfig() 里添加 image 配置：

1
// @ts-check
2

3
import mdx from '@astrojs/mdx';
4
import sitemap from '@astrojs/sitemap';
5
import { defineConfig } from 'astro/config';
6

7
export default defineConfig({
8
  // ... 其他配置
9
  integrations: [mdx(), sitemap()],
10

11
  image: {
12
    domains: ['images.example.com'],
13
    remotePatterns: [
14
      {
15
        protocol: 'https',
16
        hostname: 'images.example.com',
17
      },
18
    ],
19
  },
20
});

这里的 images.example.com 是脱敏后的占位域名。实际使用时，把它替换成自己的图片 CDN、对象存储或静态资源域名即可。

domains 和 remotePatterns

domains 适合最常见的固定域名场景：

1
image: {
2
  domains: ['images.example.com'],
3
},

remotePatterns 更适合需要限制协议、域名或路径的场景：

1
image: {
2
  remotePatterns: [
3
    {
4
      protocol: 'https',
5
      hostname: 'images.example.com',
6
      pathname: '/blog/**',
7
    },
8
  ],
9
},

如果图片都来自同一个正式 CDN，推荐先使用固定 hostname。只有在确实需要匹配多个子域名或限制路径时，再扩展 remotePatterns。

多个远程图片域名

如果站点图片来自多个独立域名，可以把它们都列出来：

1
image: {
2
  remotePatterns: [
3
    {
4
      protocol: 'https',
5
      hostname: 'images.example.com',
6
    },
7
    {
8
      protocol: 'https',
9
      hostname: 'assets.example.com',
10
    },
11
  ],
12
},

尽量避免为了省事直接放开过宽的通配范围。图片白名单越具体，越容易排查构建错误，也更符合静态站点长期维护的习惯。

不推荐的处理方式

也可以选择绕过远程图片优化，比如在使用 <Image /> 时关闭尺寸推断，或改用普通的 <img>：

1
<Image src="https://images.example.com/photo.png" inferSize={false} alt="示例图片" />

但这通常只适合临时排查。对博客和作品集来说，保留 Astro 的图片处理能力更稳妥，尤其是文章封面、插图和列表缩略图会长期复用。

修改后验证

配置完成后重新运行构建：

1
bun run build

如果错误消失，说明远程图片域名已经被 Astro 接受。后续新增图片源时，也应该优先回到 astro.config.mjs 维护白名单，而不是在单个页面里做零散绕过。