antd-mobile 服务端渲染SSR接入指南Next.js 12/13 与 Remix 完整配置【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址: https://gitcode.com/gh_mirrors/an/ant-design-mobile服务端渲染SSR是移动端 H5 应用提升首屏体验与 SEO 的常见手段而 antd-mobile 作为面向移动 Web 的 React 组件库其 SSR 支持目前仍处于实验Experimental阶段需要在 Next.js 与 Remix 中做额外配置才能正常工作。本文以 docs/guide/ssr.en.md 为核心结合 antd-mobile 源码中的 DOM 访问逻辑与构建产物结构完整讲解在 Next.js 12、Next.js 13 以及 Remix 中接入 antd-mobile 的每一步配置并说明 SSR 环境下必须注意的坑点。读完本文你将能够独立完成上述三大框架的 SSR 集成并理解这些配置背后的原理。SSR 支持现状实验性能力与已知边界antd-mobile 官方文档明确标注其对 SSR服务端渲染的支持还处在比较初始的阶段still in the initial stage如果你在使用过程中发现了 bug欢迎向官方提交 issue。这意味着 SSR 场景并非组件的默认一等公民以下三类问题需要开发者自行留意编译产物问题antd-mobile 的源码与发布产物中包含 ESM/TSX 形式的内容如 src 目录 下的组件源码以及es构建目录Node 环境无法直接解析必须通过转译transpile才能运行。浏览器 API 依赖问题组件库内部大量使用window、document、navigator等浏览器全局对象服务端渲染阶段这些对象并不存在。样式与主题初始化问题antd-mobile 通过 src/global/global.less 注入全局样式与 CSS 变量SSR 时需要确保样式文件被正确加载。因此官方文档给出了针对各框架的最小可用配置这也是本文接下来要逐一展开的内容。理解配置背后的原理antd-mobile 的 DOM 访问与产物结构在动手配置之前先理解两条关键事实它们直接决定了为什么 Next.js 需要next-transpile-modules/transpilePackages而 Remix 需要 path alias。浏览器全局对象的守卫canUseDomantd-mobile 内部对 SSR 并非毫无准备其几乎所有涉及 DOM 的工具都通过 src/utils/can-use-dom.ts 进行环境守卫export const canUseDom !!( typeof window ! undefined typeof document ! undefined window.document window.document.createElement )从源码结构看这一守卫被大量工具复用例如 src/utils/convert-px.ts 在设置根字体大小时会先判断!canUseDom || !document.body再执行src/utils/get-scroll-parent.ts 会以canUseDom ? window : undefined作为默认滚动根src/utils/validate.ts 中通过canUseDom判断后才读取navigator.userAgent做平台检测src/utils/supports-passive.ts 同样在canUseDom为真时才探测 passive event listener 支持。此外src/global/index.ts 中为移动端 Safari 修复:active伪类而注册的空touchstart监听也包裹在if (canUseDom)之内import ./global.less import { canUseDom } from ../utils/can-use-dom if (canUseDom) { // Make sure the :active CSS selector of button and a take effect document.addEventListener(touchstart, () {}, true) }这说明只要保证组件代码在 Node 侧只被解析、转译而不在渲染阶段真正触发 DOM 副作用例如弹窗类组件使用 src/utils/render-to-body.ts 动态创建容器仅会在客户端执行SSR 的初始渲染即可安全进行。这也是为何各框架配置的核心目标都是让服务端能正确解析并打包 antd-mobile。发布产物结构为什么 Remix 需要 path aliasantd-mobile 的构建脚本定义在 gulpfile.js 中其默认构建流水线会产出lib/esESM 模块、lib/cjsCommonJS 模块以及lib/bundle由 Vite 打包的 bundle见 gulpfile.js 的getViteConfigForPackage。其中lib/bundle下包含antd-mobile.es.jsES bundle与style.css合并后的样式文件这正是 Remix 配置中引用的路径来源。同时package.json 中的sideEffects字段声明了样式文件、./es/index.js、./src/index.ts、./src/global/index.ts等具有副作用这意味着打包器在 tree-shaking 时不会错误地移除全局样式与初始化逻辑。在 Next.js 12 中使用 antd-mobileNext.js 12 时代Next.js 默认不会转译node_modules中的依赖而 antd-mobile 的发布产物中包含需要转译的代码因此必须借助next-transpile-modules插件显式声明。第一步安装 next-transpile-modules按官方文档支持 npm / yarn / pnpm / bun 四种包管理器$ npm install --save-dev next-transpile-modules # or $ yarn add -D next-transpile-modules # or $ pnpm add -D next-transpile-modules # or $ bun add -D next-transpile-modules第二步配置 next.config.js在项目根目录的next.config.js中包裹配置const withTM require(next-transpile-modules)([ antd-mobile, ]); module.exports withTM({ // other Next.js configuration in your project });withTM接收一个包名数组含义是让 Next.js 在编译时把antd-mobile当作项目源码一样进行转译从而解决 Node 侧无法直接解析其 ESM 产物的问题。若项目中还依赖了其他需要转译的包可以一并加入该数组。在 Next.js 13 中使用 antd-mobileNext.js 13 引入了transpilePackages配置项可以自动转译并打包node_modules中的外部依赖从而取代了next-transpile-modules插件。配置 transpilePackages// next.config.js const nextConfig { transpilePackages: [antd-mobile], }; module.exports nextConfig;这是官方推荐的 Next.js 13 方案配置更简洁不再需要额外安装任何插件。在 app 目录下使用use client 指令如果你的项目使用了 Next.js 13 的app目录App Router由于 antd-mobile 是客户端组件库依赖window、document与 React 状态/事件系统必须在使用 antd-mobile 组件的文件顶部添加use client指令将其显式标记为客户端组件// app/page.jsx use client import { Button } from antd-mobile否则 Next.js 会在服务端渲染阶段将该模块视为 Server Component 并尝试在 Node 环境中执行从而触发浏览器 API 相关报错。注意use client标记的是模块边界app 目录下未直接使用 antd-mobile 的布局layout文件仍可保持服务端组件身份。在 Remix 中使用 antd-mobileRemix 默认在服务端使用 Node 运行时对第三方 ESM 包的处理方式与 Next.js 不同因此官方文档给出的方案是通过tsconfig.json的路径别名直接指向 antd-mobile 的预打包 bundle并手动引入样式。第一步配置 tsconfig.json 路径别名在tsconfig.json的compilerOptions.paths中新增 antd-mobile 配置并在include字段中添加global.d.ts{ include: [remix.env.d.ts, global.d.ts, **/*.ts, **/*.tsx], compilerOptions: { ... paths: { antd-mobile: [node_modules/antd-mobile/bundle/antd-mobile.es.js] } } }这里把antd-mobile解析到node_modules/antd-mobile/bundle/antd-mobile.es.js即 gulpfile.js 中由 Vite 生成的 ES bundle让 Remix 直接消费单文件打包产物绕开对散装 ESM 目录的解析问题。第二步添加 global.d.ts 类型声明由于路径别名指向的是 bundle 文件TypeScript 无法直接从其推导出 antd-mobile 的类型因此需要在项目根目录新增global.d.tsdeclare module antd-mobile { export * from antd-mobile/es; }该声明告诉 TypeScriptantd-mobile模块的类型与antd-mobile/es即 package.json 中module与types字段指向的 ES 目录一致从而获得完整的组件类型提示与检查。第三步在 app/root.tsx 引入样式antd-mobile 的全局样式在 bundle 中被合并为style.css需要在 Remix 的根路由中通过links()函数将其作为样式表加载import styles from antd-mobile/bundle/style.css; export function links() { return [{ rel: stylesheet, href: styles }]; }links()是 Remix 根路由的专用导出返回的样式表会在所有页面中生效。这一步与 src/global/global.less 中定义的全局 CSS 变量如--adm-color-primary等主题令牌相对应缺少它会出现组件样式丢失、主题变量失效的问题。常见 SSR 问题排查建议结合 antd-mobile 源码实现以下几点可以帮你快速定位 SSR 场景下的典型问题样式未生效优先检查是否按上文在 Next.js 中正确引入Next.js 会自动处理被转译包的 CSS或在 Remix 根路由links()中加载了bundle/style.css。样式由 src/global/global.less 及各个组件的.less文件编译而来gulpfile.js 的buildStyle任务会通过 Less 与 autoprefixer 处理它们。水合hydration不一致报错antd-mobile 的弹窗类组件Dialog、Toast、Popup 等通过 src/utils/render-imperatively.tsx 与 src/utils/render-to-body.ts 在运行时动态创建 DOM 容器这类命令式 API 只应在客户端事件回调中调用切勿在组件 render 阶段或服务端生命周期中执行否则会导致服务端与客户端渲染结果不一致。报 document is not defined 等浏览器 API 错误说明组件代码被在 Node 环境中执行了。检查 Next.js 中是否遗漏use client指令或transpilePackages配置Remix 中是否遗漏路径别名配置。可对照 src/utils/can-use-dom.ts 确认组件库自身的环境守卫是否生效——理论上正常配置下服务端首屏渲染不会直接触发 DOM 副作用。SSR 期间触摸/滚动相关异常antd-mobile 的弹层与滚动锁定逻辑如 src/utils/use-lock-scroll.ts依赖document.addEventListener、document.body.classList等浏览器 API这些副作用均在useEffect中触发仅在客户端执行SSR 首屏不会执行无需额外处理。官方参考资源官方文档还提供了 Remix 模板仓库 作为参考本文按规范不输出外部链接可自行搜索3lang3 antd-mobile-template查看。Next.js 官方文档中关于transpilePackages与 Server/Client Components 的说明是理解上述配置的重要背景。若需要了解 antd-mobile 的快速上手、按需引入与预构建 bundle 等其他主题可继续阅读仓库中的 docs/guide/quick-start.zh.md、docs/guide/import-on-demand.zh.md 与 docs/guide/pre-built-bundles.zh.md。小结antd-mobile 的 SSR 支持尚处实验阶段但通过以下三组最小配置即可在主流框架中完成接入Next.js 12安装next-transpile-modules并用withTM([antd-mobile])包裹配置Next.js 13在next.config.js中配置transpilePackages: [antd-mobile]app 目录下使用组件时添加use clientRemix在tsconfig.json的paths中把antd-mobile指向node_modules/antd-mobile/bundle/antd-mobile.es.js新增global.d.ts声明类型并在根路由links()中加载bundle/style.css。理解这些配置背后的原理组件库的canUseDom环境守卫、Vite 生成的 bundle 产物结构、样式全局注入机制后即使未来升级框架版本也能举一反三地完成迁移与排错。【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址: https://gitcode.com/gh_mirrors/an/ant-design-mobile创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 antd-mobile 服务端渲染SSR接入指南Next.js 12/13 与 Remix 完整配置【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址: https://gitcode.com/gh_mirrors/an/ant-design-mobile服务端渲染SSR是移动端 H5 应用提升首屏体验与 SEO 的常见手段而 antd-mobile 作为面向移动 Web 的 React 组件库其 SSR 支持目前仍处于实验Experimental阶段需要在 Next.js 与 Remix 中做额外配置才能正常工作。本文以 docs/guide/ssr.en.md 为核心结合 antd-mobile 源码中的 DOM 访问逻辑与构建产物结构完整讲解在 Next.js 12、Next.js 13 以及 Remix 中接入 antd-mobile 的每一步配置并说明 SSR 环境下必须注意的坑点。读完本文你将能够独立完成上述三大框架的 SSR 集成并理解这些配置背后的原理。SSR 支持现状实验性能力与已知边界antd-mobile 官方文档明确标注其对 SSR服务端渲染的支持还处在比较初始的阶段still in the initial stage如果你在使用过程中发现了 bug欢迎向官方提交 issue。这意味着 SSR 场景并非组件的默认一等公民以下三类问题需要开发者自行留意编译产物问题antd-mobile 的源码与发布产物中包含 ESM/TSX 形式的内容如 src 目录 下的组件源码以及es构建目录Node 环境无法直接解析必须通过转译transpile才能运行。浏览器 API 依赖问题组件库内部大量使用window、document、navigator等浏览器全局对象服务端渲染阶段这些对象并不存在。样式与主题初始化问题antd-mobile 通过 src/global/global.less 注入全局样式与 CSS 变量SSR 时需要确保样式文件被正确加载。因此官方文档给出了针对各框架的最小可用配置这也是本文接下来要逐一展开的内容。理解配置背后的原理antd-mobile 的 DOM 访问与产物结构在动手配置之前先理解两条关键事实它们直接决定了为什么 Next.js 需要next-transpile-modules/transpilePackages而 Remix 需要 path alias。浏览器全局对象的守卫canUseDomantd-mobile 内部对 SSR 并非毫无准备其几乎所有涉及 DOM 的工具都通过 src/utils/can-use-dom.ts 进行环境守卫export const canUseDom !!( typeof window ! undefined typeof document ! undefined window.document window.document.createElement )从源码结构看这一守卫被大量工具复用例如 src/utils/convert-px.ts 在设置根字体大小时会先判断!canUseDom || !document.body再执行src/utils/get-scroll-parent.ts 会以canUseDom ? window : undefined作为默认滚动根src/utils/validate.ts 中通过canUseDom判断后才读取navigator.userAgent做平台检测src/utils/supports-passive.ts 同样在canUseDom为真时才探测 passive event listener 支持。此外src/global/index.ts 中为移动端 Safari 修复:active伪类而注册的空touchstart监听也包裹在if (canUseDom)之内import ./global.less import { canUseDom } from ../utils/can-use-dom if (canUseDom) { // Make sure the :active CSS selector of button and a take effect document.addEventListener(touchstart, () {}, true) }这说明只要保证组件代码在 Node 侧只被解析、转译而不在渲染阶段真正触发 DOM 副作用例如弹窗类组件使用 src/utils/render-to-body.ts 动态创建容器仅会在客户端执行SSR 的初始渲染即可安全进行。这也是为何各框架配置的核心目标都是让服务端能正确解析并打包 antd-mobile。发布产物结构为什么 Remix 需要 path aliasantd-mobile 的构建脚本定义在 gulpfile.js 中其默认构建流水线会产出lib/esESM 模块、lib/cjsCommonJS 模块以及lib/bundle由 Vite 打包的 bundle见 gulpfile.js 的getViteConfigForPackage。其中lib/bundle下包含antd-mobile.es.jsES bundle与style.css合并后的样式文件这正是 Remix 配置中引用的路径来源。同时package.json 中的sideEffects字段声明了样式文件、./es/index.js、./src/index.ts、./src/global/index.ts等具有副作用这意味着打包器在 tree-shaking 时不会错误地移除全局样式与初始化逻辑。在 Next.js 12 中使用 antd-mobileNext.js 12 时代Next.js 默认不会转译node_modules中的依赖而 antd-mobile 的发布产物中包含需要转译的代码因此必须借助next-transpile-modules插件显式声明。第一步安装 next-transpile-modules按官方文档支持 npm / yarn / pnpm / bun 四种包管理器$ npm install --save-dev next-transpile-modules # or $ yarn add -D next-transpile-modules # or $ pnpm add -D next-transpile-modules # or $ bun add -D next-transpile-modules第二步配置 next.config.js在项目根目录的next.config.js中包裹配置const withTM require(next-transpile-modules)([ antd-mobile, ]); module.exports withTM({ // other Next.js configuration in your project });withTM接收一个包名数组含义是让 Next.js 在编译时把antd-mobile当作项目源码一样进行转译从而解决 Node 侧无法直接解析其 ESM 产物的问题。若项目中还依赖了其他需要转译的包可以一并加入该数组。在 Next.js 13 中使用 antd-mobileNext.js 13 引入了transpilePackages配置项可以自动转译并打包node_modules中的外部依赖从而取代了next-transpile-modules插件。配置 transpilePackages// next.config.js const nextConfig { transpilePackages: [antd-mobile], }; module.exports nextConfig;这是官方推荐的 Next.js 13 方案配置更简洁不再需要额外安装任何插件。在 app 目录下使用use client 指令如果你的项目使用了 Next.js 13 的app目录App Router由于 antd-mobile 是客户端组件库依赖window、document与 React 状态/事件系统必须在使用 antd-mobile 组件的文件顶部添加use client指令将其显式标记为客户端组件// app/page.jsx use client import { Button } from antd-mobile否则 Next.js 会在服务端渲染阶段将该模块视为 Server Component 并尝试在 Node 环境中执行从而触发浏览器 API 相关报错。注意use client标记的是模块边界app 目录下未直接使用 antd-mobile 的布局layout文件仍可保持服务端组件身份。在 Remix 中使用 antd-mobileRemix 默认在服务端使用 Node 运行时对第三方 ESM 包的处理方式与 Next.js 不同因此官方文档给出的方案是通过tsconfig.json的路径别名直接指向 antd-mobile 的预打包 bundle并手动引入样式。第一步配置 tsconfig.json 路径别名在tsconfig.json的compilerOptions.paths中新增 antd-mobile 配置并在include字段中添加global.d.ts{ include: [remix.env.d.ts, global.d.ts, **/*.ts, **/*.tsx], compilerOptions: { ... paths: { antd-mobile: [node_modules/antd-mobile/bundle/antd-mobile.es.js] } } }这里把antd-mobile解析到node_modules/antd-mobile/bundle/antd-mobile.es.js即 gulpfile.js 中由 Vite 生成的 ES bundle让 Remix 直接消费单文件打包产物绕开对散装 ESM 目录的解析问题。第二步添加 global.d.ts 类型声明由于路径别名指向的是 bundle 文件TypeScript 无法直接从其推导出 antd-mobile 的类型因此需要在项目根目录新增global.d.tsdeclare module antd-mobile { export * from antd-mobile/es; }该声明告诉 TypeScriptantd-mobile模块的类型与antd-mobile/es即 package.json 中module与types字段指向的 ES 目录一致从而获得完整的组件类型提示与检查。第三步在 app/root.tsx 引入样式antd-mobile 的全局样式在 bundle 中被合并为style.css需要在 Remix 的根路由中通过links()函数将其作为样式表加载import styles from antd-mobile/bundle/style.css; export function links() { return [{ rel: stylesheet, href: styles }]; }links()是 Remix 根路由的专用导出返回的样式表会在所有页面中生效。这一步与 src/global/global.less 中定义的全局 CSS 变量如--adm-color-primary等主题令牌相对应缺少它会出现组件样式丢失、主题变量失效的问题。常见 SSR 问题排查建议结合 antd-mobile 源码实现以下几点可以帮你快速定位 SSR 场景下的典型问题样式未生效优先检查是否按上文在 Next.js 中正确引入Next.js 会自动处理被转译包的 CSS或在 Remix 根路由links()中加载了bundle/style.css。样式由 src/global/global.less 及各个组件的.less文件编译而来gulpfile.js 的buildStyle任务会通过 Less 与 autoprefixer 处理它们。水合hydration不一致报错antd-mobile 的弹窗类组件Dialog、Toast、Popup 等通过 src/utils/render-imperatively.tsx 与 src/utils/render-to-body.ts 在运行时动态创建 DOM 容器这类命令式 API 只应在客户端事件回调中调用切勿在组件 render 阶段或服务端生命周期中执行否则会导致服务端与客户端渲染结果不一致。报 document is not defined 等浏览器 API 错误说明组件代码被在 Node 环境中执行了。检查 Next.js 中是否遗漏use client指令或transpilePackages配置Remix 中是否遗漏路径别名配置。可对照 src/utils/can-use-dom.ts 确认组件库自身的环境守卫是否生效——理论上正常配置下服务端首屏渲染不会直接触发 DOM 副作用。SSR 期间触摸/滚动相关异常antd-mobile 的弹层与滚动锁定逻辑如 src/utils/use-lock-scroll.ts依赖document.addEventListener、document.body.classList等浏览器 API这些副作用均在useEffect中触发仅在客户端执行SSR 首屏不会执行无需额外处理。官方参考资源官方文档还提供了 Remix 模板仓库 作为参考本文按规范不输出外部链接可自行搜索3lang3 antd-mobile-template查看。Next.js 官方文档中关于transpilePackages与 Server/Client Components 的说明是理解上述配置的重要背景。若需要了解 antd-mobile 的快速上手、按需引入与预构建 bundle 等其他主题可继续阅读仓库中的 docs/guide/quick-start.zh.md、docs/guide/import-on-demand.zh.md 与 docs/guide/pre-built-bundles.zh.md。小结antd-mobile 的 SSR 支持尚处实验阶段但通过以下三组最小配置即可在主流框架中完成接入Next.js 12安装next-transpile-modules并用withTM([antd-mobile])包裹配置Next.js 13在next.config.js中配置transpilePackages: [antd-mobile]app 目录下使用组件时添加use clientRemix在tsconfig.json的paths中把antd-mobile指向node_modules/antd-mobile/bundle/antd-mobile.es.js新增global.d.ts声明类型并在根路由links()中加载bundle/style.css。理解这些配置背后的原理组件库的canUseDom环境守卫、Vite 生成的 bundle 产物结构、样式全局注入机制后即使未来升级框架版本也能举一反三地完成迁移与排错。【免费下载链接】ant-design-mobileEssential UI blocks for building mobile web apps.项目地址: https://gitcode.com/gh_mirrors/an/ant-design-mobile创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考