拓冰网站定制 
前端UI组件【免费下载链接】next-shadcn-dashboard-starterFree, open source, AI-friendly admin dashboard template built with Next.js 16, shadcn/ui, Tailwind CSS, and TypeScript. Production-ready tables, forms, auth, and billing. MIT licensed.项目地址https://gitcode.com/gh_mirrors/ne/next-shadcn-dashboard-starter点击查看免费下载本篇技术指南以开源仓库 next-shadcn-dashboard-starter 内置的.agents/skills/next-best-practices/bundling.md为核心脉络系统讲解 Next.js 应用中第三方依赖的常见打包问题服务端不兼容包、CSS 导入、Polyfill 冗余、ESM/CommonJS 冲突以及 Webpack 到 Turbopack 的迁移。读完你可以精准识别window is not defined一类的报错根因掌握next/dynamic、serverExternalPackages、transpilePackages三种核心解决方案并用内置 Bundle Analyzer 量化验证优化效果。一、为什么 Next.js 应用会遭遇打包问题Next.js 采用「服务端组件 客户端组件」的双运行时模型服务端组件在 Node.js 环境执行、序列化后下发客户端组件才在浏览器里水合。这种架构决定了并非所有 npm 包都能原样打包——许多面向浏览器的库直接引用window、document、localStorage等 DOM API一旦在服务端渲染阶段被求值就会崩溃另一些带原生二进制绑定的包则无法被 JavaScript 打包器直接处理。.agents/skills/next-best-practices/bundling.md正是围绕这两类问题整理的一套可复用的排查与修复清单。本仓库 package.json 中恰好同时包含两类典型依赖recharts3.8.0图表库依赖浏览器环境和sharp0.35.3原生图像处理库是本文所有方案最贴近现实的验证对象。二、服务端不兼容包Server-Incompatible Packages2.1 错误特征速认当某个包被服务端组件直接 import 并执行时最常见的报错是以下四类几乎可以立刻锁定「浏览器 API 泄漏到服务端」这一根因ReferenceError: window is not defined ReferenceError: document is not defined ReferenceError: localStorage is not defined Module not found: Cant resolve fs其中前三类是浏览器全局对象在 Node 环境不存在最后一种则相反——某些包在构建期尝试解析 Node 内置模块fs而客户端打包器不提供该模块。2.2 方案一标记为客户端专属dynamic ssr: false如果该包只在客户端需要典型如图表、富文本编辑器、地图 SDK最干净的做法是关闭它的服务端渲染// Bad: Fails - package uses window import SomeChart from some-chart-library; export default function Page() { return SomeChart /; } // Good: Use dynamic import with ssr: false import dynamic from next/dynamic; const SomeChart dynamic(() import(some-chart-library), { ssr: false }); export default function Page() { return SomeChart /; }next/dynamic的ssr: false意味着该模块仅在浏览器端加载服务端渲染时以占位符跳过从根本上杜绝 DOM API 在服务端被访问。仓库实证本仓库未直接使用dynamic()而是采用了更符合 RSC 惯例的「客户端组件边界」策略——图表组件全部放在use client组件中。area-graph.tsx 首行声明use client后直接import { Area, AreaChart, CartesianGrid, XAxis } from recharts由客户端组件作为运行边界隔离浏览器 API与服务端组件互不干扰。这两种写法在结果上等价都保证了 recharts 不会在服务端执行。2.3 方案二从服务端 bundle 中外部化serverExternalPackages对于必须在服务端运行、但打包困难的包原生绑定、循环依赖、ORM应通过serverExternalPackages让 Next.js 在服务端构建时跳过打包、按 Node.js 原生 require 解析// next.config.js module.exports { serverExternalPackages: [problematic-package] };文档明确给出该类包的三种典型场景带原生绑定的包sharp、bcrypt无法良好打包的包部分 ORM存在循环依赖的包仓库实证next.config.ts 是 TypeScript 形态的 Next.js 16 配置目前未显式设置serverExternalPackages。值得注意的是sharp被 package.json 的overrides字段锁定为^0.35.3——它是 Next.js 镜像优化next/image的内部依赖由框架自行外部化处理一般无需手动配置这恰好说明了「框架内置处理过的包不必重复外部化」这条经验。若你引入 bcrypt、canvas 等原生绑定库再按上述格式追加即可。2.4 方案三客户端组件包装器Client Component Wrapper当第三方库被多处使用、且与服务端数据流混用时可以建一个薄客户端包装组件把「库的使用」限制在客户端边界内服务端只需引用这个安全组件// components/ChartWrapper.tsx use client; import { Chart } from chart-library; export function ChartWrapper(props) { return Chart {...props} /; } // app/page.tsx (server component) import { ChartWrapper } from /components/ChartWrapper; export default function Page() { return ChartWrapper data{data} /; }这个模式也是本仓库的实际组织方式所有 recharts 的使用都被收拢在use client的图表组件如 bar-graph.tsx、pie-graph.tsx内再经由 shadcn 的 chart.tsx 统一封装服务端页面只 import 组件而不触碰库本身。三、CSS 导入用 import 代替link打包器优化 CSS去重、压缩、拆分、按路由加载的前提是 CSS 进入模块依赖图因此文档明确要求用 import 而非手写link// Bad: Manual link tag link relstylesheet href/styles.css /; // Good: Import CSS import ./styles.css; // Good: CSS Modules import styles from ./Button.module.css;仓库实证全局样式通过 src/app/layout.tsx 的import ../styles/globals.css进入依赖图随后被 Next.js 与 Tailwind 4 的 PostCSS 管线统一处理主题 CSS 文件也按相同方式组织在 src/styles/themes/ 下。这是「CSS 走 import、参与打包优化」的标准落地。四、PolyfillNext.js 已内置无需重复加载Next.js 构建产物默认包含一套基础 polyfill文档列出已覆盖的 APIArray.from、Object.assign、Promise、fetch、Map、Set、Symbol、URLSearchParams以及另外 50 余项。因此从 polyfill.io 等 CDN 额外注入是纯冗余既增加请求又可能造成全局污染// Bad: Redundant polyfills script srchttps://polyfill.io/v3/polyfill.min.js?featuresfetch,Promise,Array.from / // Good: Next.js includes these automatically需要特别提示此清单覆盖的是 Next.js 默认支持的语法与 API 基线。若你的业务目标浏览器超出该基线例如老版本 IE 场景仍需自行评估但这与「Next.js 常见环境下的现代浏览器」主流场景已不冲突。五、ESM/CommonJS 互操作问题5.1 错误特征当包以 ESM 格式发布、而消费方按 CommonJS 解析或反之时会看到SyntaxError: Cannot use import statement outside a module Error: require() of ES Module Module not found: ESM packages need to be imported5.2 解决方案transpilePackages把问题包加入transpilePackages让 Next.js 在打包时对该包源码做转译抹平 ESM/CommonJS 边界// next.config.js module.exports { transpilePackages: [some-esm-package, another-package] };仓库实证这是本仓库唯一显式启用的打包相关配置。next.config.ts 中写着transpilePackages: [geist]。原因可从前端字体配置反推font.config.ts 从next/font/google导入了Geist、Geist_Mono等 16 个字体变量这些字体包通过transpilePackages保证在各构建环境下都能被正确转译与按需加载。参考该写法当你引入 ESM-only 的依赖时在数组里追加包名即可。六、常见问题包速查表文档整理的高频问题包及推荐解法可直接对照排查PackageIssueSolutionsharpNative bindingsserverExternalPackages: [sharp]bcryptNative bindingsserverExternalPackages: [bcrypt]or usebcryptjscanvasNative bindingsserverExternalPackages: [canvas]rechartsUses windowdynamic(() import(recharts), { ssr: false })react-quillUses documentdynamic(() import(react-quill), { ssr: false })mapbox-glUses windowdynamic(() import(mapbox-gl), { ssr: false })monaco-editorUses windowdynamic(() import(monaco-editor/react), { ssr: false })lottie-webUses documentdynamic(() import(lottie-react), { ssr: false })补充两点实操经验其一bcryptjs是 bcrypt 的纯 JS 替代实现若不想配置原生绑定可整体替换依赖其二表格中列出的recharts、monaco-editor、lottie-web在本仓库对应的use client组件隔离方案同样成立二者按代码组织偏好任选。七、内置 Bundle AnalyzerNext.js 16.1量化「问题包到底占了多少体积、挂在哪个 chunk」是修复后验证的关键。Next.js 16.1 提供内置分析器无需安装任何额外依赖next experimental-analyze该命令会启动一个交互式 UI支持按路由、环境client/server与资源类型过滤查看模块体积与 import 调用链查看 treemap 可视化视图对比基准、留档分析时可将输出落盘next experimental-analyze --output # Output saved to .next/diagnostics/analyze提示next experimental-analyze属于实验性命令请以你实际使用的 Next.js 版本本仓库锁定next16.2.12见 package.json的 CLI 帮助为准命令名未来可能调整。八、从 Webpack 迁移到 TurbopackTurbopack 自 Next.js 15 起成为默认打包器本仓库的next16.2.12同样默认使用 Turbopack。迁移的核心原则是把自定义逻辑从 webpack 专属配置迁到跨打包器兼容的选项上// next.config.js module.exports { // Good: Works with Turbopack serverExternalPackages: [package], transpilePackages: [package], // Bad: Webpack-only - migrate away from this webpack: (config) { // custom webpack config } };serverExternalPackages与transpilePackages两个选项同时兼容 Webpack 与 Turbopack是迁移的首选落点自定义webpack(config)函数是 Webpack 专属钩子Turbopack 下不会执行长期维护应逐步移除仓库实证next.config.ts 完全遵循了这条规范——打包相关的自定义仅使用transpilePackages未出现任何webpack配置函数其中 Sentry 插件的webpack命名空间next.config.ts属于 Sentry 自身的配置结构与项目级打包器钩子无关。九、本仓库实战检查单把文档规则套用到当前仓库可以整理出一份可直接复用的核查清单检查use client边界凡 import rechartschart.tsx、area-graph.tsx、bar-graph.tsx、pie-graph.tsx或任何浏览器 API 依赖的文件确认其处于客户端组件或已被客户端组件包装CSS 一律走 import全局样式经 layout.tsx 导入globals.css不要在 JSX 里手写link不引入冗余 polyfill信任 Next.js 内置的fetch/Promise/Map/Set等 50 项基线新增依赖时对照速查表原生绑定类走serverExternalPackages浏览器 API 类走dynamic(..., { ssr: false })或客户端组件包装ESM 兼容问题走transpilePackages参照现有geist写法见 next.config.ts优化后验证用next experimental-analyze --output对比dev/build前后的 bundle 快照。按此清单执行你可以把「报错驱动修 bug」升级为「结构驱动避免踩坑」这也是本仓库将 bundling.md 沉淀为 AI 可消费技能文档的初衷——同样的规则既可以指导人写代码也可以指导 Agent 在审查或生成代码时自动规避这类打包陷阱。赞分享前端UI组件【免费下载链接】next-shadcn-dashboard-starterFree, open source, AI-friendly admin dashboard template built with Next.js 16, shadcn/ui, Tailwind CSS, and TypeScript. Production-ready tables, forms, auth, and billing. MIT licensed.项目地址https://gitcode.com/gh_mirrors/ne/next-shadcn-dashboard-starter点击查看免费下载相关推荐next-shadcn-dashboard-starter 开发指南基于 Next.js 16 shadcn/ui 模板的页面、表格、表单、主题与 RBAC 导航扩展实战next shadcn dashboard starter 开发指南基于 Next.js 16 shadcn/ui 模板的页面、表格、表单、主题与 RBA前端UI组件零基础跑通 ComfyUI视频生成WanVideoWrapper 一个下午出第一条 AI 视频零基础跑通 ComfyUI视频生成WanVideoWrapper 一个下午出第一条 AI 视频 脑子里的画面想做成视频却卡在该装什么、模型放哪、节点怎么连前端UI组件大麦抢票自动抢票工具用 ticket-purchase 把开票瞬间交给脚本的新手指南大麦抢票自动抢票工具用 ticket purchase 把开票瞬间交给脚本的新手指南 开票那一刻等你手动点完立即预订页面往往已经变成售罄。tick前端UI组件上一篇gh_mirrors/do/dockerfiles与监控告警集成案例PagerDuty实战下一篇PictureSelector Library自定义异常处理全局捕获与用户反馈创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Next.js 16 依赖打包问题排查实战：基于 next-shadcn-dashboard-starter 的 Bundling 完全指南
前端UI组件【免费下载链接】next-shadcn-dashboard-starterFree, open source, AI-friendly admin dashboard template built with Next.js 16, shadcn/ui, Tailwind CSS, and TypeScript. Production-ready tables, forms, auth, and billing. MIT licensed.项目地址https://gitcode.com/gh_mirrors/ne/next-shadcn-dashboard-starter点击查看免费下载本篇技术指南以开源仓库 next-shadcn-dashboard-starter 内置的.agents/skills/next-best-practices/bundling.md为核心脉络系统讲解 Next.js 应用中第三方依赖的常见打包问题服务端不兼容包、CSS 导入、Polyfill 冗余、ESM/CommonJS 冲突以及 Webpack 到 Turbopack 的迁移。读完你可以精准识别window is not defined一类的报错根因掌握next/dynamic、serverExternalPackages、transpilePackages三种核心解决方案并用内置 Bundle Analyzer 量化验证优化效果。一、为什么 Next.js 应用会遭遇打包问题Next.js 采用「服务端组件 客户端组件」的双运行时模型服务端组件在 Node.js 环境执行、序列化后下发客户端组件才在浏览器里水合。这种架构决定了并非所有 npm 包都能原样打包——许多面向浏览器的库直接引用window、document、localStorage等 DOM API一旦在服务端渲染阶段被求值就会崩溃另一些带原生二进制绑定的包则无法被 JavaScript 打包器直接处理。.agents/skills/next-best-practices/bundling.md正是围绕这两类问题整理的一套可复用的排查与修复清单。本仓库 package.json 中恰好同时包含两类典型依赖recharts3.8.0图表库依赖浏览器环境和sharp0.35.3原生图像处理库是本文所有方案最贴近现实的验证对象。二、服务端不兼容包Server-Incompatible Packages2.1 错误特征速认当某个包被服务端组件直接 import 并执行时最常见的报错是以下四类几乎可以立刻锁定「浏览器 API 泄漏到服务端」这一根因ReferenceError: window is not defined ReferenceError: document is not defined ReferenceError: localStorage is not defined Module not found: Cant resolve fs其中前三类是浏览器全局对象在 Node 环境不存在最后一种则相反——某些包在构建期尝试解析 Node 内置模块fs而客户端打包器不提供该模块。2.2 方案一标记为客户端专属dynamic ssr: false如果该包只在客户端需要典型如图表、富文本编辑器、地图 SDK最干净的做法是关闭它的服务端渲染// Bad: Fails - package uses window import SomeChart from some-chart-library; export default function Page() { return SomeChart /; } // Good: Use dynamic import with ssr: false import dynamic from next/dynamic; const SomeChart dynamic(() import(some-chart-library), { ssr: false }); export default function Page() { return SomeChart /; }next/dynamic的ssr: false意味着该模块仅在浏览器端加载服务端渲染时以占位符跳过从根本上杜绝 DOM API 在服务端被访问。仓库实证本仓库未直接使用dynamic()而是采用了更符合 RSC 惯例的「客户端组件边界」策略——图表组件全部放在use client组件中。area-graph.tsx 首行声明use client后直接import { Area, AreaChart, CartesianGrid, XAxis } from recharts由客户端组件作为运行边界隔离浏览器 API与服务端组件互不干扰。这两种写法在结果上等价都保证了 recharts 不会在服务端执行。2.3 方案二从服务端 bundle 中外部化serverExternalPackages对于必须在服务端运行、但打包困难的包原生绑定、循环依赖、ORM应通过serverExternalPackages让 Next.js 在服务端构建时跳过打包、按 Node.js 原生 require 解析// next.config.js module.exports { serverExternalPackages: [problematic-package] };文档明确给出该类包的三种典型场景带原生绑定的包sharp、bcrypt无法良好打包的包部分 ORM存在循环依赖的包仓库实证next.config.ts 是 TypeScript 形态的 Next.js 16 配置目前未显式设置serverExternalPackages。值得注意的是sharp被 package.json 的overrides字段锁定为^0.35.3——它是 Next.js 镜像优化next/image的内部依赖由框架自行外部化处理一般无需手动配置这恰好说明了「框架内置处理过的包不必重复外部化」这条经验。若你引入 bcrypt、canvas 等原生绑定库再按上述格式追加即可。2.4 方案三客户端组件包装器Client Component Wrapper当第三方库被多处使用、且与服务端数据流混用时可以建一个薄客户端包装组件把「库的使用」限制在客户端边界内服务端只需引用这个安全组件// components/ChartWrapper.tsx use client; import { Chart } from chart-library; export function ChartWrapper(props) { return Chart {...props} /; } // app/page.tsx (server component) import { ChartWrapper } from /components/ChartWrapper; export default function Page() { return ChartWrapper data{data} /; }这个模式也是本仓库的实际组织方式所有 recharts 的使用都被收拢在use client的图表组件如 bar-graph.tsx、pie-graph.tsx内再经由 shadcn 的 chart.tsx 统一封装服务端页面只 import 组件而不触碰库本身。三、CSS 导入用 import 代替link打包器优化 CSS去重、压缩、拆分、按路由加载的前提是 CSS 进入模块依赖图因此文档明确要求用 import 而非手写link// Bad: Manual link tag link relstylesheet href/styles.css /; // Good: Import CSS import ./styles.css; // Good: CSS Modules import styles from ./Button.module.css;仓库实证全局样式通过 src/app/layout.tsx 的import ../styles/globals.css进入依赖图随后被 Next.js 与 Tailwind 4 的 PostCSS 管线统一处理主题 CSS 文件也按相同方式组织在 src/styles/themes/ 下。这是「CSS 走 import、参与打包优化」的标准落地。四、PolyfillNext.js 已内置无需重复加载Next.js 构建产物默认包含一套基础 polyfill文档列出已覆盖的 APIArray.from、Object.assign、Promise、fetch、Map、Set、Symbol、URLSearchParams以及另外 50 余项。因此从 polyfill.io 等 CDN 额外注入是纯冗余既增加请求又可能造成全局污染// Bad: Redundant polyfills script srchttps://polyfill.io/v3/polyfill.min.js?featuresfetch,Promise,Array.from / // Good: Next.js includes these automatically需要特别提示此清单覆盖的是 Next.js 默认支持的语法与 API 基线。若你的业务目标浏览器超出该基线例如老版本 IE 场景仍需自行评估但这与「Next.js 常见环境下的现代浏览器」主流场景已不冲突。五、ESM/CommonJS 互操作问题5.1 错误特征当包以 ESM 格式发布、而消费方按 CommonJS 解析或反之时会看到SyntaxError: Cannot use import statement outside a module Error: require() of ES Module Module not found: ESM packages need to be imported5.2 解决方案transpilePackages把问题包加入transpilePackages让 Next.js 在打包时对该包源码做转译抹平 ESM/CommonJS 边界// next.config.js module.exports { transpilePackages: [some-esm-package, another-package] };仓库实证这是本仓库唯一显式启用的打包相关配置。next.config.ts 中写着transpilePackages: [geist]。原因可从前端字体配置反推font.config.ts 从next/font/google导入了Geist、Geist_Mono等 16 个字体变量这些字体包通过transpilePackages保证在各构建环境下都能被正确转译与按需加载。参考该写法当你引入 ESM-only 的依赖时在数组里追加包名即可。六、常见问题包速查表文档整理的高频问题包及推荐解法可直接对照排查PackageIssueSolutionsharpNative bindingsserverExternalPackages: [sharp]bcryptNative bindingsserverExternalPackages: [bcrypt]or usebcryptjscanvasNative bindingsserverExternalPackages: [canvas]rechartsUses windowdynamic(() import(recharts), { ssr: false })react-quillUses documentdynamic(() import(react-quill), { ssr: false })mapbox-glUses windowdynamic(() import(mapbox-gl), { ssr: false })monaco-editorUses windowdynamic(() import(monaco-editor/react), { ssr: false })lottie-webUses documentdynamic(() import(lottie-react), { ssr: false })补充两点实操经验其一bcryptjs是 bcrypt 的纯 JS 替代实现若不想配置原生绑定可整体替换依赖其二表格中列出的recharts、monaco-editor、lottie-web在本仓库对应的use client组件隔离方案同样成立二者按代码组织偏好任选。七、内置 Bundle AnalyzerNext.js 16.1量化「问题包到底占了多少体积、挂在哪个 chunk」是修复后验证的关键。Next.js 16.1 提供内置分析器无需安装任何额外依赖next experimental-analyze该命令会启动一个交互式 UI支持按路由、环境client/server与资源类型过滤查看模块体积与 import 调用链查看 treemap 可视化视图对比基准、留档分析时可将输出落盘next experimental-analyze --output # Output saved to .next/diagnostics/analyze提示next experimental-analyze属于实验性命令请以你实际使用的 Next.js 版本本仓库锁定next16.2.12见 package.json的 CLI 帮助为准命令名未来可能调整。八、从 Webpack 迁移到 TurbopackTurbopack 自 Next.js 15 起成为默认打包器本仓库的next16.2.12同样默认使用 Turbopack。迁移的核心原则是把自定义逻辑从 webpack 专属配置迁到跨打包器兼容的选项上// next.config.js module.exports { // Good: Works with Turbopack serverExternalPackages: [package], transpilePackages: [package], // Bad: Webpack-only - migrate away from this webpack: (config) { // custom webpack config } };serverExternalPackages与transpilePackages两个选项同时兼容 Webpack 与 Turbopack是迁移的首选落点自定义webpack(config)函数是 Webpack 专属钩子Turbopack 下不会执行长期维护应逐步移除仓库实证next.config.ts 完全遵循了这条规范——打包相关的自定义仅使用transpilePackages未出现任何webpack配置函数其中 Sentry 插件的webpack命名空间next.config.ts属于 Sentry 自身的配置结构与项目级打包器钩子无关。九、本仓库实战检查单把文档规则套用到当前仓库可以整理出一份可直接复用的核查清单检查use client边界凡 import rechartschart.tsx、area-graph.tsx、bar-graph.tsx、pie-graph.tsx或任何浏览器 API 依赖的文件确认其处于客户端组件或已被客户端组件包装CSS 一律走 import全局样式经 layout.tsx 导入globals.css不要在 JSX 里手写link不引入冗余 polyfill信任 Next.js 内置的fetch/Promise/Map/Set等 50 项基线新增依赖时对照速查表原生绑定类走serverExternalPackages浏览器 API 类走dynamic(..., { ssr: false })或客户端组件包装ESM 兼容问题走transpilePackages参照现有geist写法见 next.config.ts优化后验证用next experimental-analyze --output对比dev/build前后的 bundle 快照。按此清单执行你可以把「报错驱动修 bug」升级为「结构驱动避免踩坑」这也是本仓库将 bundling.md 沉淀为 AI 可消费技能文档的初衷——同样的规则既可以指导人写代码也可以指导 Agent 在审查或生成代码时自动规避这类打包陷阱。赞分享前端UI组件【免费下载链接】next-shadcn-dashboard-starterFree, open source, AI-friendly admin dashboard template built with Next.js 16, shadcn/ui, Tailwind CSS, and TypeScript. Production-ready tables, forms, auth, and billing. MIT licensed.项目地址https://gitcode.com/gh_mirrors/ne/next-shadcn-dashboard-starter点击查看免费下载相关推荐next-shadcn-dashboard-starter 开发指南基于 Next.js 16 shadcn/ui 模板的页面、表格、表单、主题与 RBAC 导航扩展实战next shadcn dashboard starter 开发指南基于 Next.js 16 shadcn/ui 模板的页面、表格、表单、主题与 RBA前端UI组件零基础跑通 ComfyUI视频生成WanVideoWrapper 一个下午出第一条 AI 视频零基础跑通 ComfyUI视频生成WanVideoWrapper 一个下午出第一条 AI 视频 脑子里的画面想做成视频却卡在该装什么、模型放哪、节点怎么连前端UI组件大麦抢票自动抢票工具用 ticket-purchase 把开票瞬间交给脚本的新手指南大麦抢票自动抢票工具用 ticket purchase 把开票瞬间交给脚本的新手指南 开票那一刻等你手动点完立即预订页面往往已经变成售罄。tick前端UI组件上一篇gh_mirrors/do/dockerfiles与监控告警集成案例PagerDuty实战下一篇PictureSelector Library自定义异常处理全局捕获与用户反馈创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考