[DISCUSSION] FAQ-开发常见问题及解决方案

[ukeSJTU]

🚧 Nomad 项目 FAQ & 常见问题解答 🚧

目标: 本 Issue 旨在收集和解答在为 Nomad 项目贡献代码时，可能会遇到的常见问题、技术难点和最佳实践。特别是针对本项目使用的现代化技术栈（Next.js App Router, Server Components, Drizzle ORM, Neon DB 分支等）。

结构:

• 本帖（主楼）包含一个目录 (Table of Contents - ToC)，链接到下方评论区中的具体 Q&A。
• 每一个独立的评论 (Comment) 代表一个问答条目 (Q&A)。

如何使用:

1. 浏览下方的 目录，点击链接跳转到你感兴趣的问题。
2. 如果你遇到了新的问题，请先在此处搜索，或在评论区浏览。
3. 如果你发现了新的问题及其解决方案，欢迎添加一条新的评论，并通知项目维护者 (@ukeSJTU @Wilfrid-Hervey @dzx0902 ) 更新主楼的目录。

---

目录

A. 开发环境与配置

• A1 - Next.js 15 + Turbopack 在 Windows 环境下无法解析 Google Fonts 模块
• A2 - Next.js 环境变量的加载优先级
• A3 - Turbo 工具守护进程启动失败

B. Next.js 框架相关问题 (React 19 / Next.js 15)

• B1 - 为什么 pnpm dev 运行正常时突然崩溃，浏览器显示 "Internal Server Error"？

C. 数据库相关问题 (PostgreSQL / Drizzle-ORM)

• C1 - 为什么我修改 Schema 后，集成测试 (pnpm test:integration) 报错 ECONNREFUSED 或 Failed query？
• C2 - 如何使用 db:seed 脚本为我的数据库填充数据？

D. 测试相关问题 (Vitest / Playwright)

• D1 - 运行 Storybook 单元测试出现意外报错

E. 界面相关问题 (Shadcn / Tailwind / Storybook)

F. 其他常见问题

---

FAQ 模板

这是在下方添加每一条具体问答时，应该遵循的格式模板。

## [问题编号]: [清晰简洁的问题标题]
*(例如: B1: 为什么我需要写这么多 Wrapper 组件？)*

---

### 问题描述

(详细描述遇到的问题或疑惑。)

### 上下文 / 症状

(描述在什么情况下会遇到这个问题？有没有具体的错误信息？可以附上简短的代码片段/界面截图/复现步骤)。

```typescript
// 示例代码片段 (如果适用)
function MyComponent() {
  // ...
}
```

### 解决方案

(提供清晰的解决方案步骤或概念解释。解释为什么会出现这个问题，以及为什么这个方案能解决它。可以附上正确的代码示例。)

```typescript
// 正确的代码示例 (如果适用)
function CorrectComponent() {
  // ...
}
```

### 相关概念

(列出与此问题相关的技术术语或概念以及参考文档或外部解决方案，方便搜索。)

- `Server Components`, `Client Components`, `use client`, `Props`, `Children`
- [Link to External Solutions or Docs](https://google.com)

[ukeSJTU]

[A1]: Next.js 15 + Turbopack 在 Windows 环境下无法解析 Google Fonts 模块

---

问题描述

在 Next.js 15 项目中使用 Turbopack 进行开发或构建时,开发服务器无法加载 Google Fonts 字体文件,导致编译失败。该问题主要出现在 Windows 环境下,使用 next/font/google 导入字体时会触发模块解析错误。

上下文 / 症状

触发条件:

• 操作系统: Windows
• Next.js 版本: 15.x
• 使用 --turbopack 参数运行开发服务器或构建命令
• 项目中使用了 next/font/google 导入 Google Fonts

重现步骤:

1. 在 package.json 中设置 "dev": "next dev --turbopack"
2. 运行 pnpm dev 或 pnpm build
3. 等待编译过程
4. 看到模块解析错误

错误信息:

Module not found: Can't resolve '@vercel/turbopack-next/internal/font/google/font'

> Build error occurred
Error: Turbopack build failed with 6 errors:
[next]/internal/font/google/geist_a71539c9.module.css:8:9
Module not found: Can't resolve '@vercel/turbopack-next/internal/font/google/font'
   6 |   font-display: swap;
   7 |   src: url(@vercel/turbopack-next/internal/font/google/font?{...}) format('woff2');
>  8 |   unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
     |         ^

问题代码示例:

// app/layout.tsx
import { Geist, Geist_Mono } from "next/font/google";

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

解决方案

此问题已经在 #126 中被解决，如果仍然遇到问题请创建新的 issue 进行反馈，并可使用下面的临时解决方案。

临时解决方案:

如果暂时无法修改字体加载方式,可以在开发环境中移除 --turbopack 参数:

// package.json
{
  "scripts": {
    "dev": "next dev",  // 移除 --turbopack
    "build": "next build"
  }
}

相关概念

• Next.js 15 - 最新版本的 Next.js 框架
• Turbopack - Next.js 的下一代打包工具,用于替代 Webpack
• next/font/google - Next.js 内置的 Google Fonts 优化加载方案
• geist - Vercel 开源的字体包,可直接作为 npm 依赖使用
• Module Resolution - 模块解析机制
• Windows Path Handling - Windows 系统路径处理差异

参考链接:

• Next.js 官方讨论: vercel/next.js#61886
• Geist Font 官方文档
• 原始 Issue: ukeSJTU/nomad#35
• 修复 PR: ukeSJTU/nomad#126

[ukeSJTU]

[D1]: 运行 Storybook 单元测试出现意外报错

---

问题描述

运行单元测试，尤其是 Storybook 的相关测试遇到意外报错，报错信息提示 "Failed to import test file ..." 但是该文件明显存在。

上下文 / 症状

当运行 pnpm test:run --project=storybook 或其他涉及到 Storybook 相关单元测试的时候，有概率（暂时无法稳定浮现）出发类似下面的报错：

 FAIL   storybook (chromium)  src/stories/user-menu.stories.tsx [ src/stories/user-menu.stories.tsx ]
Error: Failed to import test file /Volumes/External/nomad/src/stories/user-menu.stories.tsx
Caused by: TypeError: Failed to fetch dynamically imported module: http://localhost:63315/Volumes/External/nomad/src/stories/user-menu.stories.tsx?import&browserv=1763045928310

类似的：

 FAIL   storybook (chromium)  src/stories/shadcn/breadcrumb.stories.tsx [ src/stories/shadcn/breadcrumb.stories.tsx ]
Error: Failed to import test file /Volumes/External/nomad/node_modules/.pnpm/@storybook+addon-vitest@9.1.15_@vitest+browser@3.2.4_@vitest+runner@3.2.4_react-dom@19._952e17e2aa8c1164c3ee2a98b85ecd2b/node_modules/@storybook/addon-vitest/dist/vitest-plugin/setup-file.mjs
Caused by: Error: Vitest failed to find the runner. This is a bug in Vitest. Please, open an issue with reproduction.
 ❯ node_modules/.pnpm/@storybook+addon-vitest@9.1.15_@vitest+browser@3.2.4_@vitest+runner@3.2.4_react-dom@19._952e17e2aa8c1164c3ee2a98b85ecd2b/node_modules/@storybook/addon-vitest/dist/vitest-plugin/setup-file.mjs:7:29

解决方案

1. 先重新运行一次测试
2. 如果重新运行测试问题仍然存在，那么建议按照下面的方法解决：

# 删除 Storybook 缓存
rm -rf node_modules/.cache/storybook 
# 重新运行测试
pnpm test:run --project=storyboo

相关概念

• tests
• Storybook
• 疑似相同的问题

[ukeSJTU]

[C1]: 为什么我修改 Schema 后，集成测试 (pnpm test:integration) 报错 ECONNREFUSED 或 Failed query？

---

问题描述

我修改了 src/lib/schema/ 目录下的某个 schema 文件（比如 passengers.ts），并且运行了 pnpm db:push。我的本地开发服务器 (pnpm dev) 运行一切正常，数据也能正确读写。

但是，当我运行 pnpm test:integration 时，测试崩溃了，并显示 Error: connect ECONNREFUSED 或 Failed query: insert into "passengers" ... 这样的错误。

上下文 / 症状

1. 开发环境正常：pnpm dev 启动的应用可以正常连接数据库并运行。
2. db:push 已执行：你已经运行了 pnpm db:push 命令。
3. 测试环境失败：运行集成测试例如 pnpm test:run --project=integration 时，Vitest 报告数据库连接失败 或查询失败（通常是因为表结构不同步）。

# 终端输出示例 (测试文件可能并不完全一样）
 FAIL   integration  tests/integration/services/passengers.integration.test.ts > Passenger Service Integration Tests > batchDeletePassengers > should not delete already deleted passengers
Error: Failed query: insert into "passengers" ("id", "user_id", "name", "nationality", "gender", "date_of_birth", "place_of_birth", "phone", "fax", "email", "documentType", "document_number", "document_expiry_date", "is_deleted", "created_at", "updated_at") values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16), ($17, $18, $19, $20, $21, $22, $23, $24, $25, $26, $27, $28, $29, $30, $31, $32) returning "id", "user_id", "name", "nationality", "gender", "date_of_birth", "place_of_birth", "phone", "fax", "email", "documentType", "document_number", "document_expiry_date", "is_deleted", "created_at", "updated_at"
params: e0747063-03f5-4c12-be78-c1fc558fe04f,user-batch-4,Active Passenger,US,male,1990-01-01,New York,13800138000,,passenger13@test.com,passport,P00000013,2030-12-31,false,2025-11-14T06:59:36.260Z,2025-11-14T06:59:36.260Z,87c6a55a-56d7-442c-b883-4a9d15363cb0,user-batch-4,Deleted Passenger,US,male,1990-01-01,New York,13800138000,,passenger14@test.com,passport,P00000014,2030-12-31,true,2025-11-14T06:59:36.260Z,2025-11-14T06:59:36.260Z
 ❯ NodePgPreparedQuery.queryWithCache node_modules/.pnpm/drizzle-orm@0.44.7_@opentel_7b8b3cad0ff10d6e76948b9011cc3237/node_modules/src/pg-core/session.ts:73:11
 ❯ node_modules/.pnpm/drizzle-orm@0.44.7_@opentel_7b8b3cad0ff10d6e76948b9011cc3237/node_modules/src/node-postgres/session.ts:154:19
 ❯ tests/integration/services/passengers.integration.test.ts:557:24
    555|       });
    556|
    557|       const [p1, p2] = await db
       |                        ^
    558|         .insert(passengers)
    559|         .values([activePassenger, deletedPassenger])

Caused by: error: 关系 "passengers" 的 "name" 字段不存在
 ❯ node_modules/.pnpm/pg-pool@3.10.1_pg@8.16.3/node_modules/pg-pool/index.js:45:11
 ❯ node_modules/.pnpm/drizzle-orm@0.44.7_@opentel_7b8b3cad0ff10d6e76948b9011cc3237/node_modules/src/node-postgres/session.ts:161:13
 ❯ NodePgPreparedQuery.queryWithCache node_modules/.pnpm/drizzle-orm@0.44.7_@opentel_7b8b3cad0ff10d6e76948b9011cc3237/node_modules/src/pg-core/session.ts:71:12
 ❯ node_modules/.pnpm/drizzle-orm@0.44.7_@opentel_7b8b3cad0ff10d6e76948b9011cc3237/node_modules/src/node-postgres/session.ts:154:19
 ❯ tests/integration/services/passengers.integration.test.ts:557:24

解决方案

核心原因：开发库与测试库分离

本项目为开发环境和测试环境配置了两套独立的数据库。

• pnpm dev 运行时, NODE_ENV 是 development。drizzle.config.ts 会加载 .env.local 里的 DATABASE_URL。
• pnpm test 运行时，package.json 中的脚本会设置 NODE_ENV=test。drizzle.config.ts 会加载 .env.test 里的 DATABASE_URL。

陷阱在于： 你运行的 pnpm db:push 命令默认更新的是开发数据库 (development)。你的测试数据库 (test) 的 Schema 仍然是过时的，导致测试因表结构不匹配而失败。

方案一：(推荐) 推送 Schema 到测试数据库

本项目在 package.json 中提供了一个专门用于更新测试数据库的脚本。在 Schema 被修改后，你必须运行此命令：

# 此命令会读取 .env.test 的配置，并更新测试数据库
pnpm db:push:test

运行成功后，再次运行集成测试应该就能通过了。

方案二：(终极方案) 当 db:push:test 也失败时

有时候，drizzle-kit push 无法处理复杂的 Schema 变更（例如：已有的表添加非空字段、修改字段类型等）。它可能会卡住或报错。

在这种情况下，最可靠的办法是彻底重置你的测试数据库。

警告： 请确保你操作的是测试数据库（例如 nomad_test），而不是你的开发数据库。下面的操作会清除测试数据库中的所有数据！

1. 登录你的 PostgreSQL 服务
   (无论是在 Windows 本机、WSL 还是 Docker 中)

2. 删除旧的测试数据库
   （nomad_test 是示例名称，请替换为你 .env.test 中配置的库名）

   dropdb nomad_test

3. 重新创建空的测试数据库

   createdb nomad_test

4. 重新运行 db:push:test
   现在 Drizzle 会将完整的 Schema 推送到这个空数据库中，保证 100% 同步。

   pnpm db:push:test

补充：Windows / WSL / Docker 环境

• Windows (使用 WSL): 如果你使用 WSL，你的 PostgreSQL 很可能也运行在 WSL(Ubuntu) 中。上述 dropdb 和 createdb 命令在 WSL 终端中完全适用。
• Windows (本机安装 Postgres): 如果你是在 Windows 上本机安装的 PostgreSQL，你可以在 cmd 或 PowerShell 中运行 dropdb.exe 和 createdb.exe（需要将 Postgres 的 bin 目录添加到系统 PATH），或者通过 psql 命令行执行 DROP DATABASE ... 和 CREATE DATABASE ... SQL 语句。
• Docker: 如果你使用 Docker，你需要 exec
  进入容器来执行这些命令：
  docker exec -it <postgres_container_name> dropdb -U <username> nomad_test
docker exec -it <postgres_container_name> createdb -U <username> nomad_test

核心概念是相同的： 销毁并重建测试数据库，然后用 pnpm db:push:test 重新同步 Schema。

相关概念

• NODE_ENV, development, test
• Test Database (测试数据库)
• Integration Testing (集成测试)
• drizzle-kit push
• PostgreSQL CLI: dropdb, createdb
• Schema Mismatch (数据库模式不匹配)

[ukeSJTU]

[B1]: 为什么 pnpm dev 运行正常时突然崩溃，浏览器显示 "Internal Server Error"？

---

问题描述

我正在运行 pnpm dev 进行开发，一切正常。突然间，所有页面都开始显示 Internal Server Error。

我查看运行 pnpm dev 的终端，发现它显示大量 ENOENT: no such file or directory 错误，都指向 .next/static/development 目录下的 _buildManifest.js.tmp 文件。

上下文 / 症状

• 浏览器访问任何页面都显示 Internal Server Error。
• pnpm dev 终端显示类似以下的错误日志：

[2025-11-16 01:59:45] INFO: [Middleware] GET /orders/ead65134-a530-4610-b60e-b1b897e64166
 ⨯ [Error: ENOENT: no such file or directory, open '/path/to/nomad/.next/static/development/_buildManifest.js.tmp.3vpsspx71vy'] {
   errno: -2,
   code: 'ENOENT',
   syscall: 'open',
   path: '/path/to/nomad/.next/static/development/_buildManifest.js.tmp.3vpsspx71vy'
}
 ○ Compiling /_error ...
 ✓ Compiled /_error in 680ms
 ⨯ [Error: ENOENT: no such file or directory, open '/path/to/nomad/.next/static/development/_buildManifest.js.tmp.juvev8cumvq'] {
   errno: -2,
   code: 'ENOENT',
   syscall: 'open',
   path: '/path/to/nomad/.next/static/development/_buildManifest.js.tmp.juvev8cumvq'
}

• 这个问题很可能发生在你（或者是 AI 编程工具）在另一个终端窗口中运行了 pnpm build 命令之后。

解决方案

核心原因：dev 和 build 进程冲突

Next.js 使用 .next 目录作为其构建缓存和输出。

1. pnpm dev (开发服务器) 会持续地读写 .next 目录，并维护一个开发模式的构建清单 (manifest) 和缓存，以便实现热更新 (Hot Reloading)。
2. pnpm build (生产构建) 会清空并重建 .next 目录，生成一个生产模式的优化构建包。

当你同时运行这两个命令时，pnpm build 会删除或修改 pnpm dev 正在依赖的文件（比如错误中提到的 _buildManifest.js.tmp），导致开发服务器状态损坏并崩溃。

---

方案一：(如果我想继续开发)

如果你只是想继续开发，最简单的办法是重启开发服务器。

1. 在 pnpm dev 运行的终端按 Ctrl+C 停止它。
2. 重新运行 pnpm dev。

# 1. 停止当前崩溃的进程
^C
# 2. 重新启动开发服务器
pnpm dev

这会生成一个全新的开发缓存，你的应用将恢复正常。

---

方案二：(如果我想查看 build 后的结果)

如果你运行 pnpm build 的目的是为了测试生产环境的构建结果，那么你应该：

1. 在 pnpm dev 运行的终端按 Ctrl+C 停止它。
2. 运行 pnpm start 来启动一个生产服务器，它会服务于你刚刚 build 好的 .next 目录内容。

# 1. 停止开发服务器
pnpm dev
^C

# 2. 启动生产服务器
pnpm start

重要提示： pnpm start 运行的是生产模式。在此模式下，修改代码不会自动刷新页面 (没有热更新)。如果你想继续开发，请使用方案一。

相关概念

• Next.js Build Cache (.next 目录)
• pnpm dev (开发服务器)
• pnpm build (生产构建)
• pnpm start (生产服务器)
• Hot Module Replacement (HMR) (热更新)
• ENOENT (Error: No Such File or Directory)
• Process Conflict (进程冲突)

[ukeSJTU]

[C2]: 如何使用 db:seed 脚本为我的数据库填充数据？

---

问题描述

我已经创建了 .env.local 文件并运行了 pnpm db:push。现在我的本地开发数据库（nomad）是空的。

当我运行 pnpm dev 并访问应用时，所有页面（如航班搜索）都没有任何数据。我该如何填充一些假的演示数据？

另外，我的集成测试 (pnpm test:integration) 是否也需要运行这个 seed 脚本？

解决方案

本项目使用一个强大的、场景驱动 (Scenario-Driven) 的种子数据系统来填充数据库。你不应该只运行 pnpm db:seed，而应该指定一个场景。

场景一：为本地开发环境 (pnpm dev) 填充数据

你需要根据你的目的，选择一个预设的场景来运行 db:seed 命令。

快速开始：选择一个场景

我想...	使用场景	推荐命令
本地开发/调试功能	Development (开发)	pnpm db:seed --scenario=development
准备 Vercel 演示	Demo (演示)	pnpm db:seed --scenario=demo
准备课程考试数据	Exam (考试)	pnpm db:seed --scenario=exam

场景说明

1. --scenario=development (默认选项)

   • 用途： 日常本地开发。
   • 数据： fixture-faker。使用真实的城市/机场/航司数据，并用 Faker 随机生成适量的航班和用户。
   • 特点： 启动快，数据量适中。

2. --scenario=demo

   • 用途： 用于 Vercel 部署或公开演示。
   • 数据： fixture-faker。使用全部的真实城市/机场/航司数据，并生成大量的航班和用户。
   • 特点： 数据丰富，最接近真实应用。

3. --scenario=exam

   • 用途： 课程评估或需要精确数据的场景。
   • 数据： scenario。从一个固定的 scenarioFile (如 exam-2025) 加载完全可控的、精确的数据。
   • 特点： 数据完全可控，便于设计特定测试用例。

高级用法：增量添加数据

默认情况下，所有场景都以 mode: "full" 运行，意味着它们会清空数据库中旧的种子数据再重新填充。

如果你想在不删除现有数据的情况下添加更多数据（例如，添加更多航班），你可以使用 --mode=incremental 标志：

# 在 'development' 场景的现有数据基础上，再添加一批新数据
pnpm db:seed --scenario=development --mode=incremental

场景二：为集成测试环境 (pnpm test:integration) 填充数据

你不需要，也不应该运行 db:seed 脚本。

这是一个非常重要的区别：

• pnpm db:seed -> 仅用于 development (开发) 或 demo (演示) 环境。
• pnpm test:integration -> 自动使用 "Factories" (测试工厂) 来按需创建测试数据。

测试环境的数据在每个测试用例开始前创建，并在结束后销毁，以保证测试的独立性和稳定性。

相关概念

• Data Seeding (数据填充)
• Scenarios (development, demo, exam)
• DataSource (fixture-faker vs. scenario)
• Fixture-first (基于真实数据)
• Seed Mode (full vs. incremental)
• Test Factories (测试工厂)

[ukeSJTU]

[A2]: Next.js 环境变量的加载优先级

---

问题描述

在 Next.js 项目中，存在多个环境变量文件（如 .env、.env.local、.env.example）。

核心疑惑：当同一个变量在多个地方被定义时，Next.js 实际会使用哪一个值？为什么有时修改了 .env 文件，应用中的变量值却没有更新？

---

上下文 / 症状

• 项目中同时存在 .env 和 .env.local 文件，定义了相同的环境变量
• 在开发环境 (pnpm dev) 和生产环境 (pnpm build) 中，环境变量的表现不一致
• 运行集成测试 (pnpm test:integration) 时，发现 .env.local 中的配置似乎没有生效

# .env 文件
API_URL=https://prod-api.example.com

# .env.local 文件
API_URL=http://localhost:3000/api

# 疑问: 开发时实际使用的是哪个值?

---

解决方案

Next.js 的环境变量加载遵循**"级联覆盖"（Cascading Overrides）**机制，核心原则是：越具体、越私有的配置，优先级越高。

1. 环境变量优先级规则（由高到低）

核心真理：系统级环境变量 > 所有文件配置

优先级	来源 / 文件名	说明	适用场景
1 (最高)	系统环境变量	通过 Shell (export KEY=VAL) 设置	覆盖所有文件定义
2	.env.[mode].local	如 .env.development.local	特定环境的个人本地覆盖
3	.env.local	通用个人本地覆盖	测试环境会忽略此文件
4	.env.[mode]	如 .env.development	特定环境的共享配置（通常提交到 Git）
5 (最低)	.env	基础默认配置	所有环境的兜底配置

2. 不同运行模式下的加载逻辑

开发环境 (pnpm dev)

NODE_ENV=development

# 实际加载顺序（后者覆盖前者）:
.env → .env.development → .env.local → .env.development.local → 系统环境变量

示例场景：

# .env
API_URL=https://prod-api.example.com

# .env.local
API_URL=http://localhost:3000/api

# 开发时实际使用: http://localhost:3000/api

生产环境 (pnpm build / pnpm start)

NODE_ENV=production

# 实际加载顺序:
.env → .env.production → .env.local → .env.production.local → 系统环境变量

测试环境 (NODE_ENV=test)

NODE_ENV=test

# 特殊规则: .env.local 会被忽略
# 实际加载顺序:
.env → .env.test → .env.test.local → 系统环境变量

为什么忽略 .env.local？
确保测试结果在不同开发者机器上保持一致，避免个人本地配置（如本地数据库连接）干扰测试。

3. 关键技术细节

NEXT_PUBLIC_ 前缀规则

// .env
DB_PASSWORD=secret123                    // 仅服务端可见
NEXT_PUBLIC_ANALYTICS_ID=GA-XXXXXXX     // 浏览器 + 服务端都可见

// 客户端组件
'use client'
export default function Analytics() {
  // 可以访问
  console.log(process.env.NEXT_PUBLIC_ANALYTICS_ID)
  
  // 返回 undefined (安全保护)
  console.log(process.env.DB_PASSWORD)
}

变量展开（Variable Expansion）

# .env
HOSTNAME=localhost
PORT=3000
HOST_URL=http://$HOSTNAME:$PORT  # 自动展开为 http://localhost:3000

# .env.local (覆盖)
HOSTNAME=192.168.1.100
# HOST_URL 自动变为 http://192.168.1.100:3000

4. 实用调试技巧

// 在 Next.js 应用中检查环境变量来源
console.log('Environment:', process.env.NODE_ENV)
console.log('API URL:', process.env.API_URL)

// 查看所有环境变量 (仅开发环境)
if (process.env.NODE_ENV === 'development') {
  console.log('All env vars:', process.env)
}

常见排查步骤：

1. 确认 NODE_ENV 的实际值
2. 检查是否存在系统环境变量覆盖（echo $VARIABLE_NAME）
3. 重启开发服务器（环境变量在启动时加载，不会热更新）
4. 确认 .env 文件的编码格式（应为 UTF-8）

---

相关概念

• Environment Variables (环境变量)
• Cascading Overrides (级联覆盖机制)
• NODE_ENV (development / production / test)
• .env.local vs .env.test (本地覆盖 vs 测试专用)
• NEXT_PUBLIC_ prefix (客户端变量暴露)
• Variable Expansion (变量引用展开)

参考文档：

• Next.js Environment Variables 官方文档