Next.js：.next/BUILD_ID是什么？为何缺失？--trace-warnings为何无效？

两周前创建的Next.js应用此前运行正常，今日启动时出现以下错误：

$ yarn start
yarn run v1.22.19
$ next start
(node:40361) ExperimentalWarning: stream/web is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
- ready started server on [::]:3000, url: http://localhost:3000
[Error: ENOENT: no such file or directory, open '/home/unclefonso/Projects/typescript-stuff/basic-site/.next/BUILD_ID'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/home/unclefonso/Projects/typescript-stuff/basic-site/.next/BUILD_ID'
}
Done in 0.51s.

尝试在package.json的scripts中添加--trace-warnings参数：

{
  "name": "basic-site",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev --trace-warnings",  <-------无效
    "build": "next build",
    "start": "next start --trace-warnings", <-----同样无效
    "lint": "next lint"
  },
  "dependencies": {
    "@types/node": "20.5.0",
    "@types/react": "18.2.20",
    "@types/react-dom": "18.2.7",
    "eslint": "8.47.0",
    "eslint-config-next": "13.4.16",
    "next": "13.4.16",
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "typescript": "5.1.6"
  }
}

执行后出现新错误：

$ yarn start
yarn run v1.22.19
$ next start --trace-warnings
(node:41733) ExperimentalWarning: stream/web is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
Unknown or unexpected option: --trace-warnings
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

咨询以下两个问题：

1. .next/BUILD_ID是什么？
2. 为何--trace-warnings无法生效？

1. 关于.next/BUILD_ID #

.next/BUILD_ID是Next.js执行next build后自动生成的文件，内部存储当前构建的唯一标识。它的作用是让Next.js生产服务器（next start）确认存在有效的构建产物，服务器会读取这个文件验证构建完整性。

你遇到的ENOENT错误，说明.next目录下没有该文件，大概率是未先执行next build就直接启动next start，或者.next目录被意外删除/清理。解决方法：先运行yarn build生成构建产物，再启动yarn start即可。

2. 为什么--trace-warnings无法生效 #

--trace-warnings是Node.js的命令行参数，并非Next.js的参数。直接加在next dev或next start后，Next.js会将其识别为未知参数，因此报错。

正确用法是把参数传给Node.js进程，而非Next.js命令，修改scripts写法如下：

{
  "scripts": {
    "dev": "NODE_OPTIONS='--trace-warnings' next dev",
    "start": "NODE_OPTIONS='--trace-warnings' next start"
  }
}

或者另一种写法：

{
  "scripts": {
    "dev": "node --trace-warnings node_modules/.bin/next dev",
    "start": "node --trace-warnings node_modules/.bin/next start"
  }
}

这样Node.js就能接收--trace-warnings参数，正常输出警告的调用栈。

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