Astro项目部署Netlify时出现filename参数未定义错误求助

错误日志 #

TypeError: The argument 'filename' must be a file URL object, file URL string, or absolute path string. Received undefined
    at new NodeError (node:internal/errors:393:5)
    at createRequire (node:internal/modules/cjs/loader:1278:11)
    at .netlify/functions-internal/chunks/image-pool.f66f99fb.mjs (/Users/user/sauce/project/.netlify/functions-internal/chunks/image-pool.f66f99fb.mjs:135:20)
    at __init (/Users/user/sauce/project/.netlify/functions-serve/entry/src/.netlify/functions-internal/entry.js:37:59)
    at /Users/user/sauce/project/.netlify/functions-internal/entry.mjs:1917:32
    at processTicksAndRejections (node:internal/process/task_queues:95:5) {
  code: 'ERR_INVALID_ARG_VALUE'
}

Node.js v18.12.1

相关代码片段 #

return fn2 && (res = (0, fn2[__getOwnPropNames(fn2)[0]])(fn2 = 0)), res;
};
var __commonJS = (cb, mod) => function __require() {
  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
};
var __export = (target, all2) => {
  for (var name in all2)
    __defProp(target, name, { get: all2[name], enumerable: true });
};
var __copyProps = (to2, from, except, desc) => {
  if (from && typeof from === "object" || typeof from === "function") {
    for (let key of __getOwnPropNames(from))
      if (!__hasOwnProp.call(to2, key) && key !== except)
        __defProp(to2, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
  }
  return to2;
};
var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target, mod));
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);

// node_modules/boolean/build/lib/boolean.js
var require_boolean = __commonJS({
  "node_modules/boolean/build/lib/boolean.js"(exports) {

项目package.json配置 #

{
  "name": "@example/basics",
  "type": "module",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/alpinejs": "^0.1.2",
    "@astrojs/image": "^0.11.0",
    "@astrojs/mdx": "^0.11.5",
    "@astrojs/netlify": "^1.3.0",
    "@astrojs/sitemap": "^1.0.0",
    "@astrojs/tailwind": "^2.1.1",
    "@datadog/browser-rum": "^4.28.1",
    "@fontsource/inter": "^4.5.14",
    "@sentry/browser": "^7.28.1",
    "@sentry/tracing": "^7.28.1",
    "@types/alpinejs": "^3.0.0",
    "alpinejs": "^3.0.0",
    "astro": "^1.6.0",
    "astro-feather-icons": "^1.0.2",
    "astro-google-analytics": "^1.0.2",
    "astro-icon": "^0.8.0",
    "astro-netlify-cms": "^0.0.1",
    "astro-seo": "^0.6.0",
    "node-fetch": "^3.3.0",
    "tailwindcss": "^3.0.24"
  },
  "engines": {
    "node": ">=16.0.0 <19.0.0"
  },
  "devDependencies": {
    "@tailwindcss/typography": "^0.5.7"
  }
}

问题背景 #

Astro本地构建运行正常，但部署到Netlify开发环境或云端后加载页面触发上述错误，仅Netlify内容管理器端点可正常访问。

解决方案 #

1. 升级核心依赖包 #

报错指向image-pool模块，和Astro图片处理、Netlify适配器的旧版本兼容问题有关。执行命令升级关键依赖：

npm update astro @astrojs/netlify @astrojs/image

升级后确保版本至少达到：

• astro >= 2.0.0
• @astrojs/netlify >= 2.0.0
• @astrojs/image >= 0.16.0

2. 检查Netlify适配器配置 #

在astro.config.mjs中确认适配器配置为函数模式，避免静态输出模式下的函数加载异常：

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/functions';

export default defineConfig({
  output: 'server',
  adapter: netlify(),
});

3. 清理构建缓存 #

• 本地删除.netlify目录，清空本地构建缓存
• 云端部署时，在Netlify控制台执行「清除缓存并重新部署」操作

4. 统一Node版本 #

确保本地与Netlify云端使用相同Node版本（建议18.x），在package.json中明确指定：

"engines": {
  "node": "18.x"
}

同时在Netlify站点设置的「构建&部署」板块，将Node版本设置为18.x。

5. 排查图片组件使用 #

检查项目中@astrojs/image组件的调用，确保所有图片路径为绝对路径或合法文件URL，避免传递undefined的路径参数。

内容的提问来源于stack exchange，提问作者Usayd