Next.js 项目中排除特定文件夹以优化构建大小并保持运行时可读性

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Next.js 项目中排除特定文件夹以优化构建大小并保持运行时可读性

2025-10-07

浏览次数：次

返回列表

Next.js 项目中排除特定文件夹以优化构建大小并保持运行时可读性

本教程探讨如何在 Next.js 项目中，特别是在使用 TypeScript 的情况下，通过配置 tsconfig.json 文件，将包含大量静态数据的文件夹从构建过程中排除，从而有效减小构建产物的大小。同时，文章将指导如何在排除后依然能在运行时访问这些文件，确保数据源的可用性，实现构建优化与数据访问的平衡。

理解构建优化与数据访问的挑战

在 next.js 项目开发中，我们常常会遇到需要管理大量静态数据文件（例如 json、csv 等）的情况。这些文件可能包含配置信息、本地化内容或应用所需的其他非代码数据。当这些文件数量庞大或体积较大时，如果它们被纳入 typescript 编译或 webpack 打包流程，可能会显著增加最终的 j*ascript 构建产物大小，导致部署时间延长、客户端加载性能下降。

然而，仅仅将这些文件从构建中排除是不够的，因为应用程序在运行时仍然需要访问这些数据。如何在减小构建体积的同时，确保这些数据文件在应用程序运行时依然可用，是我们需要解决的核心问题。

解决方案：利用 tsconfig.json 排除文件夹

对于使用 TypeScript 的 Next.js 项目，一个有效的解决方案是利用 tsconfig.json 文件中的 exclude 字段。exclude 字段用于指示 TypeScript 编译器在编译过程中忽略指定的文件或文件夹，不将其纳入编译和类型检查的范围。这意味着，被 exclude 的文件将不会被 TypeScript 编译器处理，也不会被后续的 Webpack 打包流程作为代码依赖进行打包，从而有效减小 J*aScript bundle 的大小。

以下是如何在 tsconfig.json 中配置 exclude 字段的示例：

// tsconfig.json
{
  "compilerOptions": {
    // ... 其他 TypeScript 编译器选项
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": false,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
  // 关键：将需要排除的文件夹添加到 exclude 数组中
  "exclude": ["node_modules", "MY_STATIC_DATA_FOLDER"]
}

在上述配置中，"MY_STATIC_DATA_FOLDER" 应替换为你的项目中实际存放大量 JSON 文件或其他静态数据的文件夹名称。例如，如果你的 JSON 文件位于项目根目录下的 data 文件夹中，则应将其修改为 "data"。

注意事项：

此方法主要适用于 TypeScript 项目。如果你的项目不使用 TypeScript，或者这些文件并非通过 TypeScript 导入，则需要考虑其他 Webpack 配置方法。
exclude 字段的作用是防止 TypeScript 编译器处理这些文件。这些文件本身仍然存在于项目目录中，并会在部署时被包含在服务器上（除非通过其他部署配置明确排除）。

运行时文件访问策略

尽管文件已被 tsconfig.json 排除出构建流程，但我们仍需在应用程序运行时访问它们。由于这些文件不再被打包进 J*aScript bundle，我们需要通过直接的文件系统操作来读取它们。在 Next.js 应用中，这通常意味着在服务器端（Node.js 环境）进行访问。

1. 通过 Node.js fs 模块访问 (服务器端渲染/API 路由)

Next.js 的服务器端环境（例如 getServerSideProps、API 路由或 getStaticProps 在构建时）可以完全访问 Node.js 的文件系统模块（fs）。你可以使用 fs 模块来读取被排除的静态文件。

示例：在 Next.js API 路由中读取 JSON 文件

假设你的 MY_STATIC_DATA_FOLDER 包含一个 products.json 文件，你可以在 API 路由中这样读取它：

UXbot

AI产品设计工具

185 查看详情 UXbot

// pages/api/products.js
import path from 'path';
import fs from 'fs';

export default async function handler(req, res) {
  try {
    // 获取当前工作目录 (项目根目录)
    const projectRoot = process.cwd();
    // 构建到你的静态数据文件夹的路径
    const dataDirectory = path.join(projectRoot, 'MY_STATIC_DATA_FOLDER');
    // 构建到具体 JSON 文件的路径
    const filePath = path.join(dataDirectory, 'products.json');

    // 使用 fs.promises.readFile 异步读取文件内容
    const fileContents = await fs.promises.readFile(filePath, 'utf8');
    // 解析 JSON 字符串为 J*aScript 对象
    const data = JSON.parse(fileContents);

    // 返回数据
    res.status(200).json(data);
  } catch (error) {
    console.error('Error reading products data:', error);
    res.status(500).json({ message: 'Failed to load products data' });
  }
}

关键点：

process.cwd()：返回 Node.js 进程的当前工作目录，在 Next.js 应用中通常是项目根目录。
path.join()：用于安全地拼接文件路径，避免不同操作系统路径分隔符的问题。
fs.promises.readFile()：异步读取文件内容，是处理文件 I/O 的推荐方式。
此方法只能在服务器端（Node.js 环境）使用。尝试在客户端组件中直接使用 fs 模块会导致错误。

2. 将文件放置于 public 目录 (客户端访问，但需权衡)

如果你的静态文件需要在客户端直接访问（例如，通过浏览器发起 HTTP 请求），你可以考虑将这些文件放置在 Next.js 项目的 public 目录下。public 目录下的所有内容都会在部署时直接服务，不会被 Webpack 处理或打包进 J*aScript bundle，但会作为独立的静态资源被部署。

示例：

如果你将 products.json 放在 public/MY_STATIC_DATA_FOLDER/products.json，那么在客户端或服务器端都可以通过相对路径 /MY_STATIC_DATA_FOLDER/products.json 来访问它，例如使用 fetch API：

// 客户端组件中
async function fetchProducts() {
  const res = await fetch('/MY_STATIC_DATA_FOLDER/products.json');
  const data = await res.json();
  console.log(data);
}

注意事项：

虽然 public 目录下的文件不会增加 J*aScript bundle 的大小，但它们会增加部署包的总体大小，因为这些文件仍然需要被上传到服务器并提供服务。
如果文件数量巨大且不常访问，或者只在服务器端使用，那么使用 fs 模块结合 tsconfig.json exclude 是更优的选择，因为这样可以避免将这些文件暴露给客户端或增加不必要的服务器静态资源负担。

总结与最佳实践

通过 tsconfig.json 的 exclude 字段，我们可以在 Next.js (TypeScript) 项目中有效地将特定文件夹从编译和打包流程中剔除，从而显著减小 J*aScript 构建产物的大小。结合 Node.js 的 fs 模块，我们仍然可以在服务器端安全、高效地访问这些被排除的文件。

关键点回顾：

tsconfig.json exclude： 适用于 TypeScript 项目，阻止 TypeScript 编译器处理指定文件，从而避免它们被打包进 J*aScript bundle。
服务器端 fs 模块： 在 getServerSideProps、getStaticProps 或 API 路由中使用 path 和 fs 模块直接从文件系统读取数据。这是推荐的服务器端访问方式。
public 目录： 如果文件需要在客户端直接访问，可以放置于 public 目录。但这会增加部署包的总体大小，需根据具体需求权衡。