Taro 编译时如何正确配置 alias 路径别名？

UI芳宁提问于 2026-02-26 15:21:20 阅读 26

框架

我在 Taro 项目里想用路径别名简化 import，比如把 src/utils 映射成 @/utils。按照文档在 config/index.js 里配了 alias，但编译到微信小程序时报错说找不到模块，H5 却能正常跑。是不是小程序端对 alias 支持不一样？还是我配置写错了？

这是我的配置片段：

const config = {
  // ...
  alias: {
    '@/utils': path.resolve(__dirname, '..', 'src/utils'),
    '@/components': path.resolve(__dirname, '..', 'src/components')
  }
}

Taro

我来解答赞 3 收藏

反馈

1 条解答

司马云娴 Lv1

你这个配置写法在 Taro 3.x 里其实没大问题，但坑在于 Taro 编译小程序时用的是 webpack5 的 [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias)，而微信小程序的编译器（特别是 v3 编译器）对 alias 的处理不一致，它不会自动把别名同步到自己的依赖分析里，导致模块找不到。

最稳妥的方式是：同时配置 webpack alias 和小程序的 alias 插件支持。

具体分两步：

1. 在 config/index.js 里继续保留你现在的 alias 配置，但注意路径要指向实际存在的目录，建议用绝对路径（你这样写是对的）；
2. 额外在 config/index.js 的 mini 字段里加 alias 配置，因为 Taro 会把 mini.alias 透传给小程序编译器。

比如：

const config = {

  // ...

  alias: {

    '@/utils': path.resolve(__dirname, '..', 'src/utils'),

    '@/components': path.resolve(__dirname, '..', 'src/components')

  },

  mini: {

    alias: {

      '@/utils': path.resolve(__dirname, '..', 'src/utils'),

      '@/components': path.resolve(__dirname, '..', 'src/components')

    }

  }

}

这样 H5 走 webpack alias，小程序走 mini.alias，两边都认，就不会报错了。

另外提醒一句：Taro 3.6+ 版本之后，config/index.js 的结构有调整，如果你用的是老版本，建议升级一下，或者直接用 config.dev.js 和 config.prod.js 分环境配置，效率更高。

2026-02-26 16:08