构建环境下framer-motion搭配storybook报错问题咨询

实际在组件库项目里踩过完全一样的坑，开发环境一切正常，build阶段直接抛错，版本降级完全没用，最后是按下面的顺序排查解决的：

• 首先补全依赖转译配置
  Storybook 生产构建默认跳过node_modules内的包转译，framer-motion 高版本输出的ESM语法如果没经过babel/swc转译，很容易触发语法解析报错。
  如果是用Vite作为构建引擎的Storybook 7+版本，直接在配置文件里加转译白名单：

// .storybook/main.js
export default {
  // 保留原有其他配置
  build: {
    transpilePackages: ['framer-motion'],
  }
}

如果是Webpack引擎的旧版本，修改webpack配置项：

// .storybook/main.js
export default {
  webpackFinal: async (config) => {
    config.module.rules.push({
      test: /\.m?js$/,
      include: /node_modules\/framer-motion/,
      type: 'javascript/auto'
    })
    return config
  }
}

• 处理构建环境的客户端API缺失问题
  Storybook静态构建阶段是在Node环境执行代码，framer-motion部分依赖window、document的API（比如滚动监听、布局测量相关逻辑）会直接抛引用错误。
  如果是React技术栈，可以给动效组件加客户端渲染判断：

// 所有涉及framer-motion动效的组件外层加判断
const isClient = typeof window !== 'undefined'
export default function YourComponent() {
  return isClient ? <motion.div /* 动效属性 */ /> : <div /* 静态占位 */ />
}

也可以在Storybook全局装饰器里包裹动效全局配置，跳过构建阶段的预计算：

// .storybook/preview.js
import { MotionConfig } from 'framer-motion'

export const decorators = [
  (Story) => (
    <MotionConfig reducedMotion="user">
      <Story />
    </MotionConfig>
  )
]

• 排查多版本依赖冲突
  执行对应包管理器的依赖列表检查命令，确认项目内没有多版本framer-motion共存的情况，多版本模块解析冲突也会导致构建阶段报错。
  • pnpm用户：在package.json的pnpm.overrides字段强制指定统一的framer-motion版本
  • npm用户：使用overrides字段做版本强制统一
  • yarn用户：使用resolutions字段做版本强制统一

以上路径覆盖了绝大多数版本降级无效的同类报错场景，按顺序排查基本都能定位问题。

内容的提问来源于stack exchange，提问作者kordevbaby