Next.js 中 "Module not found: Can't resolve 'fs'" 错误解析与解决方案

问题概述

当在 Next.js 应用中使用 Node.js 内置模块（如 fs、path 等）时，可能会遇到 "Module not found: Can't resolve 'fs'" 错误。这通常发生在客户端代码中尝试引用仅适用于服务器端的 Node.js 模块。

根本原因

Next.js 采用智能的代码分割策略，它会自动将代码分为：

• 服务端代码：运行在 Node.js 环境中，可以访问所有 Node.js API
• 客户端代码：运行在浏览器环境中，只能访问 Web API

Next.js 通过检测代码是否位于特定的数据获取方法中来判断代码运行环境：

// 这些方法内的代码仅在服务器端运行
export async function getServerSideProps() { /* ... */ }
export async function getStaticProps() { /* ... */ }
export async function getStaticPaths() { /* ... */ }

当你在这些方法外部使用服务器专用模块时，Next.js 会尝试将其包含在客户端包中，从而导致错误。

解决方案

方案一：正确的代码组织方式（推荐）

最佳实践

将服务器端代码严格限制在数据获取方法中

// 正确示例：仅在 getStaticProps 中使用 fs
import fs from 'fs'

export async function getStaticProps() {
  // 这里的 fs 使用是安全的
  const fileContent = fs.readFileSync('...')
  
  return {
    props: { data: fileContent }
  }
}

export default function Page({ data }) {
  // 客户端组件，不包含任何服务器端代码
  return <div>{data}</div>
}

方案二：分离服务器和客户端代码

当需要共享工具函数时，应将服务器专用代码和通用代码分离：

// lib/server-utils.js (服务器专用)
import fs from 'fs'

export function readDataFile() {
  return fs.readFileSync('data.txt', 'utf8')
}

// lib/client-utils.js (客户端可用)
export function formatData(data) {
  return data.toUpperCase()
}

// pages/index.js
import { readDataFile } from '../lib/server-utils'
import { formatData } from '../lib/client-utils'

export async function getStaticProps() {
  const data = readDataFile() // 仅在服务器端调用
  return { props: { data } }
}

export default function Page({ data }) {
  const formatted = formatData(data) // 客户端也可用
  return <div>{formatted}</div>
}

方案三：使用 server-only 包标记服务器专用代码

安装 server-only 包来明确标记服务器专用模块：

npm install server-only

// lib/server-only-module.js
import "server-only" // 这行会阻止该模块被客户端导入
import fs from 'fs'

export function useFs() {
  return fs
}

方案四：Webpack 配置修改（临时解决方案）

在 next.config.js 中配置 Webpack 忽略特定的 Node.js 模块：

next.config.js

/** @type {import('next').NextConfig} */
module.exports = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      // 客户端构建时忽略这些模块
      config.resolve.fallback = {
        ...config.resolve.fallback,
        fs: false,
        path: false,
        os: false,
      }
    }
    return config
  },
}

注意

这种方法只是让构建过程不报错，并不会真正在客户端提供这些模块的功能。建议仅作为临时解决方案。

方案五：检查并移除未使用的导入

有时错误是由于未使用的服务器端模块导入引起的：

// 错误示例：未使用的导入可能导致问题
import fs from 'fs' // 这个导入没有被使用，但可能导致错误

export default function Page() {
  return <div>Hello World</div>
}

常见场景与解决方案

场景一：使用第三方库引起的问题

某些第三方库可能包含服务器端代码：

# 将 bcrypt 替换为 bcryptjs
npm uninstall bcrypt
npm install bcryptjs

// 使用客户端兼容的版本
import bcrypt from 'bcryptjs' // 而不是 'bcrypt'

场景二：在 App Router 中使用服务器操作

在 Next.js 13+ 的 App Router 中，使用 'use server' 指令：

// app/actions.js
'use server'
import { promises as fs } from 'fs'

export async function readFileAction() {
  const content = await fs.readFile('...')
  return content
}

场景三：Edge Runtime 配置问题

确保不在 Edge Runtime 中使用 Node.js 专属 API：

// 如果需要使用 Node.js API，不要使用 edge runtime
export const runtime = 'nodejs' // 默认值，可以省略
// 不要使用：export const runtime = 'edge'

总结

解决方案	适用场景	推荐度
正确代码组织	新项目或代码重构	⭐⭐⭐⭐⭐
server-only 包	明确分离服务器代码	⭐⭐⭐⭐
Webpack 配置	临时修复或兼容旧代码	⭐⭐
替换客户端不兼容库	使用第三方库时	⭐⭐⭐

最佳实践建议

1. 始终将服务器端代码限制在数据获取方法中
2. 使用 server-only 和 client-only 包明确代码运行环境
3. 定期检查并移除未使用的导入
4. 优先使用客户端兼容的库替代服务器端专用库

通过理解 Next.js 的代码分割机制和合理组织代码结构，可以彻底避免 "Module not found: Can't resolve 'fs'" 错误，构建出更加健壮的应用。