Astro项目中使用google-apis时的fs模块解析错误问题

问题背景 #

在Astro项目中搭建API端点对接Google Sheets API，安装相关依赖后启动本地服务时遭遇fs模块解析错误。

初始错误信息 #

astro  v2.10.14 started in 257ms

  ┃ Local    http://localhost:3000/
  ┃ Network  use --host to expose

✘ [ERROR] Failed to resolve entry for package "fs". The package may have incorrect main/module/exports specified in its package.json. [plugin vite:dep-pre-bundle]

    node_modules/.pnpm/google-auth-library@9.0.0/node_modules/google-auth-library/build/src/auth/identitypoolclient.js:18:19:
      18 │ const fs = require("fs");
         ╵                    ~~~~

  This error came from the "onResolve" callback registered here:

    node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/lib/main.js:1292:20:
      1292 │       let promise = setup({
           ╵                     ^

    at setup (file:///Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/vite@4.4.9_@types+node@20.5.7/node_modules/vite/dist/node/chunks/dep-df561101.js:39921:19)
    at handlePlugins (/Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/lib/main.js:1292:21)
    at buildOrContextImpl (/Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/lib/main.js:978:5)
    at Object.buildOrContext (/Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/lib/main.js:786:5)
    at /Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/lib/main.js:2186:68
    at new Promise (<anonymous>)
    at Object.context (/Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/lib/main.js:2186:27)
    at Object.context (/Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/esbuild@0.18.20/node_modules/esbuild/lib/main.js:2026:58)
    at prepareEsbuildOptimizerRun (file:///Users/jcbraz/Projects/hugo-araujo-website/node_modules/.pnpm/vite@4.4.9_@types+node@20.5.7/node_modules/vite/dist/node/chunks/dep-df561101.js:45967:35)

✘ [ERROR] Failed to resolve entry for package "fs". The package may have incorrect main/module/exports specified in its package.json. [plugin vite:dep-pre-bundle]

    node_modules/.pnpm/google-auth-library@9.0.0/node_modules/google-auth-library/build/src/auth/googleauth.js:18:19:
      18 │ const fs = require("fs");

...

尝试的方案及新错误 #

参考相关issue修改astro.config.mjs的Vite配置，引入rollup-plugin-node-builtins并设置别名：

import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import { loadEnv } from "vite";
import rollupPluginNodeBuiltins from 'rollup-plugin-node-builtins';
const { GOOGLE_SHEETS_API, SHEET_ID } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

import tailwind from "@astrojs/tailwind";

// https://astro.build/config
export default defineConfig({
  integrations: [
    react(),
    tailwind({
      applyBaseStyles: false,
    }),
  ],
  vite: {
    resolve: {
      alias: {
        fs: rollupPluginNodeBuiltins
      }
    }
  }
});

修改后启动服务出现新错误：

🚀  astro  v2.10.14 started in 298ms

  ┃ Local    http://localhost:3000/
  ┃ Network  use --host to expose

✘ [ERROR] Could not read from file: /Users/jcbraz/Projects/hugo-araujo-website/[object Object]

    node_modules/.pnpm/google-auth-library@9.0.0/node_modules/google-auth-library/build/src/auth/identitypoolclient.js:18:19:
      18 │ const fs = require("fs");
         ╵                    ~~~~

正确解决方案 #

问题根源在于Vite在预打包时尝试处理Node.js内置模块fs，而浏览器环境并不支持该模块。由于Google Sheets API的调用逻辑应放在Astro的服务端API路由（src/pages/api/目录下的文件）中，只需调整Vite配置，明确区分服务端与客户端依赖：

1. 修改astro.config.mjs配置：

import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import { loadEnv } from "vite";
const { GOOGLE_SHEETS_API, SHEET_ID } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

import tailwind from "@astrojs/tailwind";

export default defineConfig({
  integrations: [
    react(),
    tailwind({ applyBaseStyles: false }),
  ],
  vite: {
    ssr: {
      // 将服务端依赖标记为外部资源，避免Vite在客户端打包
      external: ['google-auth-library', 'fs', 'path']
    },
    resolve: {
      // 客户端遇到这些模块时直接忽略，因为不会在浏览器中使用
      fallback: {
        fs: false,
        path: false
      }
    }
  }
});

2. 确保Google Sheets API的调用代码仅存在于src/pages/api/目录下的文件中，Astro会自动将这些文件作为服务端路由处理，不会打包到客户端代码里。

说明 #

不要使用rollup-plugin-node-builtins这类旧插件，Vite已内置对Node.js内置模块的处理逻辑，通过ssr.external和resolve.fallback配置即可解决问题，同时保证服务端与客户端依赖的正确分离。

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