runtime-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runtime Debug

运行时调试

Use this skill when reproducing runtime-bundle, module-resolution, or user-bundle inclusion regressions.

当复现运行时包、模块解析或用户包引入的回归问题时，可使用本技能。

Local Repro Discipline

本地复现规范

Mirror CI env vars when reproducing CI failures.
Key variables:
```
IS_WEBPACK_TEST=1
```
forces webpack (turbopack is default),
```
NEXT_SKIP_ISOLATE=1
```
skips packing next.js.
For module-resolution validation, always rerun without
```
NEXT_SKIP_ISOLATE=1
```
.

复现CI失败问题时，镜像CI环境变量。
关键变量：
```
IS_WEBPACK_TEST=1
```
强制使用webpack（默认是turbopack），
```
NEXT_SKIP_ISOLATE=1
```
跳过Next.js的打包步骤。
进行模块解析验证时，务必在不设置
```
NEXT_SKIP_ISOLATE=1
```
的情况下重新运行。

Stack Trace Visibility

堆栈追踪可见性

Set

__NEXT_SHOW_IGNORE_LISTED=true

to disable the ignore-list filtering in dev server error output. By default, Next.js collapses internal frames to

at ignore-listed frames

, which hides useful context when debugging framework internals. Defined in

packages/next/src/server/patch-error-inspect.ts

设置

__NEXT_SHOW_IGNORE_LISTED=true

可禁用开发服务器错误输出中的忽略列表过滤功能。默认情况下，Next.js会将内部调用栈折叠为

at ignore-listed frames

，这会在调试框架内部逻辑时隐藏有用的上下文信息。该配置定义于

packages/next/src/server/patch-error-inspect.ts

文件中。

User-Bundle Regression Guardrail

用户包回归防护措施

When user

next build

starts bundling internal Node-only helpers unexpectedly:

Inspect route trace artifacts (
```
.next/server/.../page.js.nft.json
```
).

Inspect traced server chunks for forbidden internals (e.g.

next/dist/server/stream-utils/node-stream-helpers.js

node:stream/promises

Add a
```
test-start-webpack
```
assertion that reads the route trace and traced server chunks, and fails on forbidden internals. This validates user-project bundling (not publish-time runtime bundling).

当用户执行

next build

时意外打包了仅适用于Node.js的内部辅助工具时：

检查路由追踪产物（
```
.next/server/.../page.js.nft.json
```
）。
检查已追踪的服务器代码块，确认是否包含禁用的内部模块（例如
```
next/dist/server/stream-utils/node-stream-helpers.js
```
、
```
node:stream/promises
```
）。
添加一个
```
test-start-webpack
```
断言，读取路由追踪信息和已追踪的服务器代码块，若检测到禁用的内部模块则触发失败。此操作可验证用户项目的打包情况（而非发布时的运行时打包）。

Bundle Tracing / Inclusion Proof

包追踪 / 引入验证

To prove what user bundling includes, emit webpack stats from the app's

next.config.js

// next.config.js
module.exports = {
  webpack(config) {
    config.profile = true
    return config
  },
}

Then use

stats.toJson({ modules: true, chunks: true, reasons: true })

and diff

webpack-stats-server.json

between modes. This gives concrete inclusion reasons (e.g. which module required

node:stream/promises

) and is more reliable than analyzer HTML alone.

若要验证用户打包包含的内容，可从应用的

next.config.js

中输出webpack统计信息：

// next.config.js
module.exports = {
  webpack(config) {
    config.profile = true
    return config
  },
}

随后使用

stats.toJson({ modules: true, chunks: true, reasons: true })

，并对比不同模式下的

webpack-stats-server.json

文件。这将提供具体的模块引入原因（例如哪个模块依赖了

node:stream/promises

），比仅使用分析器HTML报告更可靠。