如何解决Vite构建共享包中next/link在Next.js内无法预取的问题

以下是针对性的排查和解决步骤：

• 避免共享包独立安装Next.js
  共享组件包不应将next作为自身的dependencies或devDependencies，而是放在peerDependencies中，确保组件使用宿主Next.js应用提供的next/link实例。
  在共享包的package.json中调整：

  {
    "peerDependencies": {
      "next": "^13.0.0 || ^14.0.0",
      "react": "^18.0.0",
      "react-dom": "^18.0.0"
    }
  }
  

  之后删除共享包的node_modules和锁文件，重新安装依赖。

• 配置Vite排除Next.js相关依赖
  确保Vite构建共享包时，不会将next/link、next/router等模块打包进产物，而是保留对宿主应用的依赖引用。在共享包的vite.config.js中添加Rollup外部依赖配置：

  import { defineConfig } from 'vite'
  import react from '@vitejs/plugin-react'
  
  export default defineConfig({
    plugins: [react()],
    build: {
      lib: {
        entry: 'src/index.js',
        name: 'SharedComponents',
        fileName: (format) => `shared-components.${format}.js`,
      },
      rollupOptions: {
        external: ['next/link', 'next/router', 'react', 'react-dom'],
        output: {
          globals: {
            'next/link': 'NextLink',
            'next/router': 'NextRouter',
            react: 'React',
            'react-dom': 'ReactDOM'
          }
        }
      }
    }
  })
  

• 验证transpilePackages配置准确性
  确认next.config.js中的transpilePackages数组包含共享包的完整名称（比如包名为@acme/shared-ui，就必须写全称，不能简写）：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    transpilePackages: ['@acme/shared-ui'],
    // 其他配置...
  }
  
  module.exports = nextConfig
  

• 检查Link组件的使用规范
  确保共享组件中next/link的用法与宿主Next.js版本匹配：

  • Pages Router（Next.js 12及以下）：必须用<Link>包裹原生<a>标签

    import Link from 'next/link'
    
    export const NavLink = () => (
      <Link href="/dashboard">
        <a>Dashboard</a>
      </Link>
    )
    

  • App Router（Next.js 13+）：<Link>可直接作为容器，无需嵌套<a>

    import Link from 'next/link'
    
    export const NavLink = () => (
      <Link href="/dashboard">Dashboard</Link>
    )
    

  同时排查是否有自定义的onClick事件阻止了默认行为，导致预取逻辑无法触发。

• 清除缓存并重新构建

  • 删除宿主应用的.next文件夹
  • 删除共享包的dist（或构建产物）文件夹，重新执行构建命令
  • 重新安装宿主应用的依赖，确保依赖引用正确

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