npm 配置

weapp-vite 内建了“小程序 npm 依赖落位”能力。它不仅仅是“把依赖打进 miniprogram_npm”，还允许你精细控制：

主包放哪些依赖
插件产物放哪些依赖
哪些依赖下沉到特定分包
单个 npm 包构建时用什么底层 Vite 配置

默认依赖分类规则

默认情况下：

dependencies 与 devDependencies 都优先进入 Vite 的正常打包流程
只有“明确的小程序包”或你显式指定的包，才会进入小程序 npm 构建

这里的“明确的小程序包”通常指包自身带有 miniprogram 字段，例如：

tdesign-miniprogram
@vant/weapp

如果你仍想沿用旧规则，也可以切回 legacy 模式，让根 package.json.dependencies 默认进入 miniprogram_npm。

`weapp.npm`

类型：

{
  enable?: boolean
  cache?: boolean
  strategy?: 'explicit' | 'legacy'
  include?: (string | RegExp)[]
  mainPackage?: {
    dependencies?: false | (string | RegExp)[]
  }
  pluginPackage?: {
    dependencies?: false | (string | RegExp)[]
  }
  subPackages?: Record<string, {
    dependencies?: (string | RegExp)[]
  }>
  buildOptions?: (options: NpmBuildOptions, pkgMeta: BuildNpmPackageMeta) => NpmBuildOptions | undefined
  alipayNpmMode?: 'miniprogram_npm' | 'node_modules'
}

import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    npm: {
      enable: true,
      cache: true,
      strategy: 'explicit',
      include: ['dayjs'],
      mainPackage: {
        dependencies: false,
      },
      pluginPackage: {
        dependencies: ['dayjs'],
      },
      subPackages: {
        'packages/order': {
          dependencies: [/^tdesign-miniprogram/, 'dayjs'],
        },
      },
      buildOptions(options, { name }) {
        if (name === 'dayjs') {
          return {
            ...options,
            build: {
              ...options.build,
              minify: false,
              sourcemap: true,
            },
          }
        }
        return options
      },
      alipayNpmMode: 'node_modules',
    },
  },
})

字段说明

`enable`

类型：boolean

是否启用内建 npm 构建。

关闭后：

weapp-vite 不再自动构建小程序 npm 目录
若源码里仍保留 require('pkg') / 包路径引用，则需要你自己处理，例如改为开发者工具手动构建 npm

`cache`

类型：boolean

是否启用 npm 构建缓存。

默认缓存目录：

node_modules/weapp-vite/.cache/

适用建议：

日常开发保留 true
如果怀疑 npm 构建结果陈旧，再临时设 false 或手动清缓存

`strategy`

类型：'explicit' | 'legacy'

控制 npm 构建候选集的默认分类方式。

行为：

explicit：默认值。dependencies / devDependencies 都先按普通依赖走 Vite 打包；只有小程序包或显式命中的包才进入 npm 构建
legacy：兼容旧行为。根 package.json.dependencies 默认作为 npm 构建候选

`include`

类型：(string | RegExp)[] | undefined

额外指定哪些包要进入 npm 构建候选集。

说明：

字符串命中包名时，也会覆盖其子路径导入
include 只决定“哪些包进入 npm 构建”
最终落到主包 / 插件 / 分包，仍由下面的 mainPackage.dependencies、pluginPackage.dependencies、subPackages 决定

`mainPackage.dependencies`

类型：false | (string | RegExp)[] | undefined

控制主包里的 npm 依赖范围。

行为：

undefined：默认按当前 npm 候选集处理
false：不输出主包 npm 目录
数组：只输出命中的依赖

`pluginPackage.dependencies`

类型：false | (string | RegExp)[] | undefined

控制插件产物里的 npm 依赖范围。

仅在以下前提下有意义：

配置了 weapp.pluginRoot
当前走到了插件构建链路

`subPackages`

类型：Record<string, { dependencies?: (string | RegExp)[] }>

控制特定分包内的 npm 依赖落位。

适合：

把只在某个分包使用的依赖下沉到该分包
减少主包体积

`buildOptions`

类型：(options, pkgMeta) => options | undefined

允许你在“构建单个 npm 包”的那一层覆写底层 Vite 配置。

常见场景：

给个别依赖关闭压缩
给个别依赖开启 sourcemap
调整构建 target

TIP

这里操作的是“npm 包内部构建用的 Vite 配置对象”。若你需要理解其中 build.* 字段的完整语义，请直接看 Vite 中文官方配置文档。

`alipayNpmMode`

类型：'miniprogram_npm' | 'node_modules'

用于控制支付宝平台的本地 npm 输出目录风格。

默认是：

node_modules

如果你的历史链路或团队约定需要走微信风格目录，可切到：

miniprogram_npm

常见落位策略

主包尽量瘦身

export default defineConfig({
  weapp: {
    npm: {
      mainPackage: {
        dependencies: false,
      },
      subPackages: {
        'packages/order': {
          dependencies: ['dayjs'],
        },
      },
    },
  },
})

适合把明确只在分包用到的依赖下沉出去。

默认内联，仅指定包进入 npm 构建

export default defineConfig({
  weapp: {
    npm: {
      include: ['dayjs'],
      subPackages: {
        'packages/order': {
          dependencies: ['dayjs'],
        },
      },
    },
  },
})

适合让普通依赖默认内联，只有指定包进入 miniprogram_npm。

插件单独携带 npm

export default defineConfig({
  weapp: {
    srcRoot: 'miniprogram',
    pluginRoot: 'plugin',
    npm: {
      pluginPackage: {
        dependencies: ['dayjs'],
      },
      mainPackage: {
        dependencies: false,
      },
    },
  },
})

适合主应用和插件同仓维护，但只希望插件产物包含指定 npm 包。

与顶层 `build.*` 的边界

顶层 Vite build.* 影响的是主项目构建。

weapp.npm.buildOptions 影响的是：

小程序 npm 依赖包自己的内部构建

两者不要混淆。

更多原生字段请看：

Vite 中文官方配置文档 · build

常见问题

npm 构建内容没更新

优先尝试：

把 cache 设为 false
清理 node_modules/weapp-vite/.cache/
重新构建

分包体积过大

优先检查：

mainPackage.dependencies
subPackages.<root>.dependencies

为什么 `dependencies` 里的包没有自动进入 `miniprogram_npm`？

因为默认 strategy 是 explicit：

普通依赖会优先被 Vite 内联打包
只有小程序包或 npm.include / mainPackage.dependencies / pluginPackage.dependencies / subPackages.<root>.dependencies 显式命中的包，才会进入 npm 构建

如果你要恢复旧行为，请改成：

export default defineConfig({
  weapp: {
    npm: {
      strategy: 'legacy',
    },
  },
})

支付宝平台目录不符合预期

优先检查：

weapp.platform
weapp.npm.alipayNpmMode

如果你继续处理分包边界，请回看分包配置。如果你要处理库模式，则继续看库模式配置。

npm 配置 ​

默认依赖分类规则 ​

weapp.npm ​

字段说明 ​

enable ​

cache ​

strategy ​

include ​

mainPackage.dependencies ​

pluginPackage.dependencies ​

subPackages ​

buildOptions ​

alipayNpmMode ​

常见落位策略 ​

主包尽量瘦身 ​

默认内联，仅指定包进入 npm 构建 ​

插件单独携带 npm ​

与顶层 build.* 的边界 ​

常见问题 ​

npm 构建内容没更新 ​

分包体积过大 ​

为什么 dependencies 里的包没有自动进入 miniprogram_npm？ ​

支付宝平台目录不符合预期 ​