如何在Netlify部署带Node.js适配器的SSR Astro站点？解决sharp模块缺失问题

问题描述 #

部署使用Node.js适配器的服务端渲染（SSR）Astro站点到Netlify时，生产环境出现如下报错：

Runtime.ImportModuleError - Error: Cannot find module 'sharp' Require stack: - /var/task/.netlify/functions-internal/entry.js - /var/task/entry.js - /var/runtime/index.mjs

同时发现Netlify Functions面板存在未手动指定的entry函数，怀疑与此报错相关。

现有配置 #

astro.config.mjs

import { defineConfig } from "astro/config";
import preact from "@astrojs/preact";
import sitemap from "@astrojs/sitemap";
import image from "@astrojs/image";
import compress from "astro-compress";

import node from "@astrojs/node";

export default defineConfig({
  site: "https://kluzko.tech",
  trailingSlash: "always",
  output: "server",
  adapter: node({
    mode: "standalone",
  }),
  integrations: [
    preact({
      compat: true,
    }),
    sitemap({
      customPages: ["https://kluzko.tech/about", "https://kluzko.tech/contact"],
    }),
    image({
      serviceEntryPoint: "@astrojs/image/sharp",
    }),
    compress({
      css: true,
      html: false,
      img: true,
      js: true,
      svg: false,
      logger: 1,
    }),
  ],
  vite: {
    ssr: {
      noExternal: ["react-hot-toast"],
    },
  },
});

netlify.toml

[build]
  command = "pnpm build"
  publish = "dist"

解决方案 #

1. 修复Sharp模块缺失问题 #

Sharp是Astro Image集成依赖的图像处理库，需确保它被正确纳入生产依赖并打包：

• 检查package.json，将sharp移至dependencies（而非devDependencies），执行命令调整：

  pnpm remove sharp --save-dev
  pnpm add sharp --save
  

• 在astro.config.mjs的Vite配置中，将sharp加入noExternal列表，避免Vite将其外部化：

  vite: {
    ssr: {
      noExternal: ["react-hot-toast", "sharp"],
    },
  },
  

2. 适配Netlify的Node适配器部署配置 #

使用Astro Node适配器的standalone模式时，需调整Netlify配置以正确识别服务入口：
修改netlify.toml为：

[build]
  command = "pnpm build"
  publish = "dist/client"
  functions = "dist/server"

[[redirects]]
  from = "/*"
  to = "/.netlify/functions/entry"
  status = 200

• publish指向dist/client：Astro Node适配器构建后，静态资源存放在此目录
• functions指向dist/server：SSR服务逻辑打包在该目录，Netlify会自动识别其中的entry函数
• 重定向规则：将所有请求转发到SSR函数，确保路由由Astro统一处理

3. 清理缓存重新部署 #

避免旧构建残留导致的异常：

• 本地执行pnpm clean，或手动删除dist、node_modules后重新安装依赖并构建
• 在Netlify后台部署页面，选择「Clear cache and deploy site」选项重新部署

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