在 Next.js 13.4+ 中使用 Turbopack…

在 Next.js 13.4+ 项目中使用 Turbopack 做增量打包、配置、缓存优化、代码分割、Webpack 迁移和排错时使用。

适用场景

解决思路

1. 按 Turbopack 增量计算模型组织代码和依赖，利用 Turbo engine 的函数级缓存，只重算变更内容，并保留跨构建持久缓存。
2. 依赖 Rust 原生性能、内置 TypeScript/JSX 支持和 Next.js 集成，避免用 webpack 配置包裹 Turbopack。
3. 采用项目结构：src/app 放 App Router（layout.tsx、page.tsx、globals.css），src/components 放共享组件，src/lib 放工具函数，public 放静态资源，根目录保留 next.config.js、tsconfig.json、package.json。
4. 在 Next.js 13.4+ 开发模式启用 Turbopack：运行 next dev --turbo，或在 package.json 的 scripts.dev 中设为 next dev --turbo。
5. 在 next.config.js 中使用 experimental.turbo 放 Turbopack 专属配置。
6. 在 next.config.js 的 turbopack.rules 配置自定义 loader，例如 '*.svg' 使用 loaders ['@svgr/webpack'] 且 as '*.js'，'*.mdx' 使用 loaders ['@mdx-js/loader']。
7. 在 next.config.js 的 turbopack.resolveAlias 配置别名，例如 '@components': './src/components'、'@lib': './src/lib'、'@styles': './src/styles'。
8. 在 next.config.js 的 turbopack.resolveExtensions 配置解析扩展名，例如 ['.tsx','.ts','.jsx','.js','.json']。
9. 利用内置支持，不为 TypeScript、JSX/TSX、CSS、CSS Modules、PostCSS、静态资源配置额外 loader。
10. 不配置 css-loader、postcss-loader、babel-loader（用于 @babel/preset-env 时）。
11. 配置 tsconfig.json 推荐 compilerOptions：target ES2017，lib 为 dom、dom.iterable、esnext，allowJs true，skipLibCheck true，strict true，noEmit true，esModuleInterop true，module esnext，moduleResolution bundler，resolveJsonModule true，isolatedModules true，jsx preserve，incremental true，baseUrl .，paths 中 @/* 指向 ./src/*。
12. 配置 TypeScript 路径别名，例如 baseUrl .，paths 中 @components/* 指向 src/components/*、@lib/* 指向 src/lib/*、@styles/* 指向 src/styles/*。
13. 按 Atomic Design 组织组件：components/atoms 放基础块，molecules 放原子组合，organisms 放复杂组件，templates 放页面布局；app/page.tsx 和 lib/utils.ts 相应放置。
14. 每个组件采用独立目录：Button.tsx、Button.module.css、Button.test.tsx、index.ts。
15. 使用 next/dynamic 做动态导入，例如 dynamic(() => import('@/components/HeavyComponent'), { loading: () => <p>Loading...</p>, ssr: false })。
16. 利用 app/ 路由自动按路由代码分割。
17. 手动拆分大组件：对 ChartComponent、EditorComponent 等分别用 dynamic(() => import('./ChartComponent')) 和 dynamic(() => import('./EditorComponent'))。
18. 利用 Turbo engine：函数级缓存增量构建，只重算变更，跨构建持久缓存。
19. 为缓存优化代码：保持模块小而专注，让一个模块变更不使其他模块缓存失效。
20. 将工具函数按关注点拆分，例如分别导出 formatDate 和 formatCurrency，避免频繁变更的大工具文件。
21. 模块组织上保持小而专注，最小化跨模块依赖，少用 barrel exports。
22. 导入时优先具体导入，例如 import { Button } from '@/components/Button'。
23. 避免导入整个库，例如不要 import _ from 'lodash'，改用 import debounce from 'lodash/debounce'。
24. 使用 const assertions 改善 tree-shaking，例如 const ROUTES = { home: '/', about: '/about', contact: '/contact' } as const。
25. CSS Modules：import styles from './Component.module.css'，在 className 中使用 styles.container。
26. 全局 CSS：在 app/layout.tsx 中 import './globals.css'。
27. 配置 Tailwind CSS 的 content 范围：'./src/**/*.{js,ts,jsx,tsx,mdx}' 和 './app/**/*.{js,ts,jsx,tsx,mdx}'。
28. 环境变量放 .env.local，例如 NEXT_PUBLIC_API_URL=https://api.example.com、DATABASE_URL=postgresql://...。
29. 客户端环境变量必须使用 NEXT_PUBLIC_ 前缀，例如 process.env.NEXT_PUBLIC_API_URL；服务端专用变量如 process.env.DATABASE_URL 不要暴露到客户端。
30. 测试组织：组件测试与组件同目录，例如 Button/Button.test.tsx；集成测试放 src/__tests__/pages/home.test.tsx。
31. 测试最佳实践：为工具函数写单元测试，组件用 React Testing Library，端到端用 Cypress 或 Playwright，并让测试靠近被测代码。
32. 检查 tsconfig.json 的 baseUrl 和 paths 必须与实际结构匹配，例如 @/* 指向 ./src/*。
33. 出现缓存问题时运行 rm -rf .next 清除 Turbopack 缓存。
34. 检查依赖与 Turbopack 兼容性；部分 webpack 插件可能不能直接使用；用 Next.js 配置替代 webpack 配置。
35. 从 Webpack 迁移时，不再使用直接 webpack.config.js，改用 next.config.js 自定义，并为部分 loader 找 Turbopack 等价物。
36. 迁移时保持不变的写法：import syntax、dynamic imports、CSS Modules、TypeScript support。
37. 遵循 Do：使用 Next.js 配置做自定义，利用内置 TypeScript/JSX 支持，为增量计算组织代码，使用 dynamic imports 做代码分割，保持模块专注小。
38. 避免直接 webpack 配置、频繁变更的大 barrel 文件、对抗 Next.js 约定、忽略 TypeScript path 配置。
39. 调试时用 NEXT_DEBUG_TURBOPACK=1 next dev --turbo 输出详细日志。
40. 构建分析时运行 ANALYZE=true next build。
41. 常见问题处理：首次构建慢是正常，后续构建会快。
42. Module not found 时检查 tsconfig.json path aliases。
43. CSS 不加载时检查 import 语法。
44. Type errors 时单独运行 tsc --noEmit。

适用边界 · 注意事项

• 项目无法使用 Next.js 13.4+，或必须直接维护 webpack.config.js 的自定义构建时。
• 重度依赖 webpack 专属插件且没有 Turbopack 等价物时。
• 需要生产环境长期稳定且所需特性尚未被 Turbopack 支持时。