部署Remix应用至Netlify时缺失未直接引入的依赖问题求助

尝试将Remix应用部署到Netlify，严格按照官方文档操作，但执行netlify deploy时，Netlify反复提示缺失多个未直接引入的依赖（比如@react-hook/debounce）。手动添加一两个后，仍会继续提示下一个缺失依赖，陷入循环。即便是从头搭建新项目，问题依然存在，当前使用pnpm作为包管理器，Netlify官方宣称原生支持pnpm。

报错示例 #

Error: In file "C:\..\PROJECT_NAME\.netlify\functions-internal\server.js"
Cannot find module '@react-hook/debounce'

新项目配置文件 #

netlify.toml #

[build]
  command = "pnpm run build"
  publish = "public"

[dev]
  command = "remix watch"
  port = 3000

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

[[headers]]
  for = "/build/*"
  [headers.values]
    "Cache-Control" = "public, max-age=31536000, s-maxage=31536000"

package.json #

{
  "private": true,
  "sideEffects": false,
  "scripts": {
    "build": "pnpm run build:css && remix build",
    "build:css": "tailwindcss -m -i ./styles/app.css -o app/styles/app.css",
    "dev": "concurrently \"pnpm run dev:css\" \"remix dev\"",
    "dev:css": "tailwindcss -w -i ./styles/app.css -o app/styles/app.css"
  },
  "dependencies": {
    "@netlify/functions": "^1.0.0",
    "@remix-run/netlify": "^1.7.3",
    "@remix-run/node": "^1.7.3",
    "@remix-run/react": "^1.7.3",
    "cross-env": "^7.0.3",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@remix-run/dev": "^1.7.3",
    "@remix-run/eslint-config": "^1.7.3",
    "@remix-run/serve": "^1.7.3",
    "@types/react": "^18.0.15",
    "@types/react-dom": "^18.0.6",
    "autoprefixer": "^10.4.12",
    "concurrently": "^7.5.0",
    "eslint": "^8.23.1",
    "postcss": "^8.4.18",
    "tailwindcss": "^3.2.1",
    "typescript": "^4.7.4"
  },
  "engines": {
    "node": ">=14"
  }
}

remix.config.js #

/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
  serverBuildTarget: "netlify",
  server:
    process.env.NETLIFY || process.env.NETLIFY_LOCAL
      ? "./server.js"
      : undefined,
  ignoredRouteFiles: ["**/.*"],
  // appDirectory: "app",
  // assetsBuildDirectory: "public/build",
  // serverBuildPath: ".netlify/functions-internal/server.js",
  // publicPath: "/build/",
};

问题根源与解决方案 #

根源分析 #

问题核心是pnpm默认的非扁平化依赖结构与Netlify函数构建逻辑不兼容。pnpm为了节省磁盘空间，默认会将依赖嵌套存储，而Netlify在构建服务器函数时，不会自动遍历深层嵌套的依赖目录，导致服务器构建产物无法找到间接依赖。

解决步骤 #

1. 启用pnpm依赖扁平化
   在项目根目录创建.npmrc文件，添加以下配置：

   shamefully-hoist=true
   

   该配置会强制pnpm将所有依赖提升到顶层node_modules，和npm/yarn的依赖结构一致，确保Netlify能找到所有间接依赖。

2. 清除缓存并重新构建

   • 清除pnpm全局缓存：

     pnpm store prune
     

   • 删除本地项目的依赖和构建产物：

     rm -rf node_modules .netlify public/build
     

   • 重新安装依赖并构建：

     pnpm install
     pnpm run build
     

3. 本地验证后部署
   先执行本地开发命令确认无报错：

   netlify dev
   

   验证通过后，执行部署：

   netlify deploy --prod
   

4. 可选：升级相关依赖版本
   旧版本的Remix Netlify适配器可能存在依赖处理bug，建议升级到最新稳定版：

   pnpm update @remix-run/netlify @remix-run/node @remix-run/dev
   

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