flags

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feature Flags

功能标志

Use this skill when adding or changing framework feature flags in Next.js internals.

当在Next.js内部添加或更改框架功能标志时，请使用此skill。

Required Wiring

必要的配置流程

All flags need:

config-shared.ts

(type) →

config-schema.ts

(zod). If the flag is consumed in user-bundled code (client components, edge routes,

app-page.ts

template), also add it to

define-env.ts

for build-time injection. Runtime-only flags consumed exclusively in pre-compiled bundles can skip

define-env.ts

所有标志都需要：

config-shared.ts

（类型）→

config-schema.ts

（Zod）。如果该标志在用户打包的代码（客户端组件、边缘路由、

app-page.ts

模板）中使用，还需将其添加到

define-env.ts

以实现构建时注入。仅在预编译包中使用的纯运行时标志可以跳过

define-env.ts

。

Where the Flag Is Consumed

标志的使用场景

Client/bundled code only (e.g.

__NEXT_PPR

in client components):

define-env.ts

is sufficient. Webpack/Turbopack replaces

process.env.X

at the user's build time.

Pre-compiled runtime bundles (e.g. code in

app-render.tsx

): The flag must also be set as a real

process.env

var at runtime, because

app-render.tsx

runs from pre-compiled bundles where

define-env.ts

doesn't reach. Two approaches:

Runtime env var: Set in
```
next-server.ts
```
+
```
export/worker.ts
```
. Both code paths stay in one bundle. Simple but increases bundle size.
Separate bundle variant: Add DefinePlugin entry in
```
next-runtime.webpack-config.js
```
(scoped to
```
bundleType === 'app'
```
), new taskfile tasks, update
```
module.compiled.js
```
selector, and still set env var in
```
next-server.ts
```
+
```
export/worker.ts
```
for bundle selection. Eliminates dead code but adds build complexity.

For runtime flags, also add the field to the

NextConfigRuntime

Pick type in

config-shared.ts

仅客户端/打包代码（例如客户端组件中的

__NEXT_PPR

）：只需配置

define-env.ts

即可。Webpack/Turbopack会在用户构建时替换

process.env.X

。

预编译运行时包（例如

app-render.tsx

中的代码）：该标志还必须在运行时设置为真实的

process.env

变量，因为

app-render.tsx

从预编译包运行，

define-env.ts

无法作用于这些包。有两种方法：

运行时环境变量：在
```
next-server.ts
```
+
```
export/worker.ts
```
中设置。两个代码路径保留在同一个包中。实现简单但会增加包体积。
单独的包变体：在
```
next-runtime.webpack-config.js
```
中添加DefinePlugin条目（限定为
```
bundleType === 'app'
```
）、新的taskfile任务、更新
```
module.compiled.js
```
选择器，同时仍需在
```
next-server.ts
```
+
```
export/worker.ts
```
中设置环境变量以选择包。这种方式可以消除无用代码，但会增加构建复杂度。

对于运行时标志，还需在

config-shared.ts

的

NextConfigRuntime

Pick类型中添加对应字段。

Runtime-Bundle Model

运行时包模型

Runtime bundles are built by
```
next-runtime.webpack-config.js
```
(rspack) via
```
taskfile.js
```
bundle tasks.

Bundle selection occurs at runtime in

src/server/route-modules/app-page/module.compiled.js

based on

process.env

vars.

Variants:

{turbo/webpack} × {experimental/stable/nodestreams/experimental-nodestreams} × {dev/prod}

= up to 16 bundles per route type.

```
define-env.ts
```
affects user bundling, not pre-compiled runtime internals.
```
process.env.X
```
checks in
```
app-render.tsx
```
are either replaced by DefinePlugin at runtime-bundle-build time, or read as actual env vars at server startup. They are NOT affected by the user's defines from
```
define-env.ts
```
.
Gotcha: DefinePlugin entries in
```
next-runtime.webpack-config.js
```
must be scoped to the correct
```
bundleType
```
(e.g.
```
app
```
only, not
```
server
```
) to avoid replacing assignment targets in
```
next-server.ts
```
.

运行时包由
```
next-runtime.webpack-config.js
```
（rspack）通过
```
taskfile.js
```
的打包任务构建。

包选择在运行时由

src/server/route-modules/app-page/module.compiled.js

根据

process.env

变量决定。

变体：

{turbo/webpack} × {experimental/stable/nodestreams/experimental-nodestreams} × {dev/prod}

= 每种路由类型最多16个包。

```
define-env.ts
```
影响用户打包，而非预编译的运行时内部代码。
```
app-render.tsx
```
中的
```
process.env.X
```
检查要么在运行时包构建时被DefinePlugin替换，要么在服务器启动时读取实际环境变量。它们不受用户从
```
define-env.ts
```
定义的内容影响。
注意事项：
```
next-runtime.webpack-config.js
```
中的DefinePlugin条目必须限定为正确的
```
bundleType
```
（例如仅
```
app
```
，而非
```
server
```
），以避免替换
```
next-server.ts
```
中的赋值目标。