build-start

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build & Start

构建与启动

Quick Start

快速开始

When building or starting the application:

Development:
```
npm run dev
```
or
```
npm run dev:turbo
```
Production Build:
```
npm run build
```
Production Start:
```
npm run start
```
Vercel Build:
```
npm run build:vercel
```

当构建或启动应用时：

开发环境：
```
npm run dev
```
或
```
npm run dev:turbo
```
生产构建：
```
npm run build
```
生产环境启动：
```
npm run start
```
Vercel构建：
```
npm run build:vercel
```

Commands

常用命令

Development Server

开发服务器

bash

undefined

bash

undefined

Standard development server

标准开发服务器

npm run dev

Development with Turbopack (faster)

使用Turbopack启动开发服务（速度更快）

npm run dev:turbo


**Port**: 3000 (default)  
**Features**: Hot reload, error overlay, fast refresh

npm run dev:turbo


**端口**：3000（默认）  
**特性**：热重载、错误浮层、快速刷新

Production Build

生产构建

bash

undefined

bash

undefined

Standard production build

标准生产构建

npm run build

Vercel-optimized build

Vercel优化版构建

npm run build:vercel


**Output**: `.next` directory  
**Time**: Typically 20-60 seconds  
**Verification**: Check for build errors and warnings

npm run build:vercel


**输出**：`.next` 目录  
**耗时**：通常20-60秒  
**验证**：检查构建错误和警告

Production Server

生产服务器

bash

undefined

bash

undefined

Start production server

启动生产服务器

npm run start


**Port**: 3000 (default)  
**Environment**: Requires `NODE_ENV=production`

npm run start


**端口**：3000（默认）  
**环境要求**：需要设置 `NODE_ENV=production`

Deploy y caché (Vercel)

部署与缓存（Vercel）

Después del deploy, para que los assets y el HTML se actualicen rápido en todos los dispositivos:

bash

undefined

部署完成后，为了让静态资源和HTML在所有设备上快速更新：

bash

undefined

Purgar CDN + Data Cache (requiere Vercel CLI y vercel login)

清除CDN + 数据缓存（需要安装Vercel CLI并登录Vercel账号）

npm run cache:purge


- **Panel Vercel**: Settings → Caches → Purge CDN Cache + Purge Data Cache.
- **Assets**: Las URLs de tenant llevan `?v=<commit-sha>` (cache busting); `/images` y `/tenants` tienen caché 24h. Ver `docs/CACHE_PURGE_ANTES_DEPLOY.md`.
- **Flujo recomendado**: deploy → luego `npm run cache:purge` (o purgar desde el panel).

npm run cache:purge


- **Vercel控制面板**：设置 → 缓存 → 清除CDN缓存 + 清除数据缓存
- **静态资源**：租户URL会携带`?v=<commit-sha>`参数（缓存破除）；`/images`和`/tenants`路径的缓存时长为24小时。详见`docs/CACHE_PURGE_ANTES_DEPLOY.md`
- **推荐流程**：部署 → 执行`npm run cache:purge`（或从控制面板清除缓存）

Build Process

构建流程

Pre-build Steps

前置构建步骤

The build process includes automatic pre-build steps:

React Cache Polyfill:
```
scripts/create-react-cache-polyfill.js
```
- Creates polyfill for
```
react/cache
```
  compatibility
- Required for Next.js 16 compatibility

构建流程包含自动执行的前置步骤：

React Cache Polyfill：
```
scripts/create-react-cache-polyfill.js
```
- 为
```
react/cache
```
  兼容性创建polyfill
- 是Next.js 16兼容的必要依赖

Build Configuration

构建配置

Key build settings in

next.config.js

TypeScript: Build errors ignored (temporary)
Compiler: Console removal in production
Output: Optimized for Vercel deployment
Bundle Analyzer: Enabled with
```
ANALYZE=true
```
Cache busting:
```
NEXT_PUBLIC_ASSETS_VERSION
```
(desde
```
VERCEL_GIT_COMMIT_SHA
```
en Vercel) para que las URLs de assets de tenant cambien en cada deploy

next.config.js

中的核心构建设置：

TypeScript：暂时忽略构建错误
编译器：生产环境移除控制台输出
输出：针对Vercel部署优化
打包分析器：设置
```
ANALYZE=true
```
即可启用
缓存破除：
```
NEXT_PUBLIC_ASSETS_VERSION
```
（Vercel环境下取自
```
VERCEL_GIT_COMMIT_SHA
```
），确保每次部署时租户静态资源的URL都会更新

Common Build Issues

常见构建问题

TypeScript Errors

TypeScript错误

If TypeScript errors block the build:

bash

undefined

如果TypeScript错误阻塞了构建：

bash

undefined

Check TypeScript errors

检查TypeScript错误

npx tsc --noEmit

Build ignores TypeScript errors (configured in next.config.js)

构建时忽略TypeScript错误（已在next.config.js中配置）

npm run build

undefined

npm run build

undefined

Memory Issues

内存问题

If build fails due to memory:

bash

undefined

如果构建因内存不足失败：

bash

undefined

Increase Node memory limit

提升Node内存上限

NODE_OPTIONS="--max-old-space-size=4096" npm run build

undefined

NODE_OPTIONS="--max-old-space-size=4096" npm run build

undefined

Module Resolution Errors

模块解析错误

If you see module resolution errors:

Clear
```
.next
```
directory:
```
rm -rf .next
```
Clear node_modules:
```
rm -rf node_modules && npm install
```
Rebuild:
```
npm run build
```

如果遇到模块解析错误：

清除
```
.next
```
目录：
```
rm -rf .next
```
清除node_modules：
```
rm -rf node_modules && npm install
```
重新构建：
```
npm run build
```

Verification Checklist

验证检查清单

After building:

Build completes without errors
No critical warnings in console
```
.next
```
directory created successfully
Production server starts correctly
Pages load without runtime errors
Environment variables loaded correctly

构建完成后检查：

构建无错误完成
控制台无严重警告
```
.next
```
目录成功创建
生产服务器正常启动
页面加载无运行时错误
环境变量正确加载

Environment Variables

环境变量

Required for production build:

```
NEXT_PUBLIC_*
```
variables (exposed to client)
Database connection strings
API keys and secrets
Tenant configuration

Check

.env.local.example

for required variables.

生产构建所需的环境变量：

以
```
NEXT_PUBLIC_*
```
开头的变量（暴露给客户端）
数据库连接字符串
API密钥和私密信息
租户配置

可查看

.env.local.example

了解所需变量。

Performance Targets

性能指标

Build Time: < 20s (target)
First Load JS: < 500KB
Bundle Size: Optimized with code splitting

构建时长：目标<20秒
首次加载JS体积：<500KB
打包体积：通过代码分割优化

Troubleshooting

问题排查

Build Fails with React Cache Error

构建因React Cache错误失败

bash

undefined

bash

undefined

Ensure polyfill script runs

确保polyfill脚本已执行

node scripts/create-react-cache-polyfill.js npm run build

undefined

node scripts/create-react-cache-polyfill.js npm run build

undefined

Build Succeeds but Runtime Errors

构建成功但出现运行时错误

Check browser console for errors
Verify environment variables are set
Check server logs for API errors
Verify database connections

检查浏览器控制台报错
验证环境变量是否正确设置
检查服务端日志中的API错误
验证数据库连接

Slow Build Times

构建速度慢

Use Turbopack:
```
npm run dev:turbo
```
Check for large dependencies
Review bundle analyzer output
Consider incremental builds

使用Turbopack：
```
npm run dev:turbo
```
检查是否存在体积过大的依赖
查看打包分析器输出
考虑使用增量构建

Key Files

核心文件

```
next.config.js
```
- Build configuration (incl. env NEXT_PUBLIC_ASSETS_VERSION)
```
package.json
```
- Build scripts (
```
cache:purge
```
para purgar caché Vercel)
```
scripts/create-react-cache-polyfill.js
```
- Pre-build script
```
docs/CACHE_PURGE_ANTES_DEPLOY.md
```
- Guía purga de caché y actualización de assets
```
.env.local
```
- Environment variables

```
next.config.js
```
- 构建配置（包含环境变量NEXT_PUBLIC_ASSETS_VERSION）
```
package.json
```
- 构建脚本（包含用于清除Vercel缓存的
```
cache:purge
```
命令）
```
scripts/create-react-cache-polyfill.js
```
- 前置构建脚本
```
docs/CACHE_PURGE_ANTES_DEPLOY.md
```
- 缓存清除与静态资源更新指南
```
.env.local
```
- 环境变量配置