Vite构建npm包时测试站点无法识别别名'my-pkg'的解决方法

我希望创建一个名为'my-pkg'的npm包，同时在同一项目下搭建一个简易测试网站来验证该包的功能。项目结构如下：

my-pkg
  server // 测试网站文件夹
    index.tsx // 此处将导入该包
    index.html
  src
    index.tsx // 包源码
  vite.config.ts

我的Vite配置文件如下：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import dts from "vite-plugin-dts";
import * as path from "path";

export default defineConfig({
    plugins: [
        react(),
        dts({
            include: ["src/**/*.tsx"],
        }),
    ],
    build: {
        lib: {
            entry: [path.resolve(__dirname, "src/index.tsx")],
            formats: ["umd"],
            fileName: (format) => `my-pkg.${format}.js`,
            name: "MyPkg",
        },
        rollupOptions: {
            external: ["react", "react-dom"],
            output: {
                globals: {
                    react: "React",
                    "react-dom": "ReactDOM"
                },
            },
        },
        cssCodeSplit: true,
        sourcemap: true,
        assetsInlineLimit: Infinity,
    },
    resolve: {
        alias: { // 配置该别名是为了让测试站点可以通过'my-pkg'导入包
            "my-pkg": path.resolve(__dirname, "./src/index.tsx")
        },
    },
    server: {
        host: "localhost",
        port: 3000,
        open: "/server/index.html",
        strictPort: true,
        fs: {
            cachedChecks: false,
        },
    },
});

我已在tsconfig.json中配置了路径，且在VS Code中可以正常使用：

"paths": {
   "my-pkg": ["./src/index.tsx"]
}

执行vite build可以正常生成所需的包，但运行vite server启动测试网站时，系统提示找不到'my-pkg'。请问为何别名在测试站点中不生效？该如何解决？

原因分析 #

Vite的resolve.alias直接指向单个文件时，可能存在模块解析优先级问题，尤其是测试站点入口位于server目录下时，Vite的解析流程可能未正确触发该别名匹配；另外无精确匹配的别名可能和其他路径产生混淆，导致解析失败。

解决办法 #

1. 给别名添加精确匹配后缀 #

修改resolve.alias，添加$后缀确保仅精确匹配import ... from 'my-pkg'的语句，避免误匹配：

resolve: {
    alias: {
        "my-pkg$": path.resolve(__dirname, "./src/index.tsx")
    },
},

2. 将别名指向源码目录（适配多模块场景） #

如果后续包会扩展子模块，建议将别名指向src目录，让Vite自动读取目录下的index.tsx作为入口：

resolve: {
    alias: {
        "my-pkg": path.resolve(__dirname, "./src")
    },
},

这种配置既支持根路径导入，也支持import ... from 'my-pkg/components/xxx'这类子模块导入。

3. 使用npm link模拟真实包依赖（推荐） #

该方式更贴近真实项目使用npm包的场景，还能验证打包后的包是否正常：

• 项目根目录执行：npm link，将本地my-pkg链接到全局npm仓库
• 进入server目录执行：npm link my-pkg，将全局的my-pkg关联到测试站点的依赖中
• 移除Vite配置中的resolve.alias，测试站点的导入逻辑就和真实项目完全一致

4. 用插件同步tsconfig路径到Vite别名 #

安装vite-tsconfig-paths插件，让Vite自动读取tsconfig.json的paths配置，避免手动维护两份别名：

1. 安装插件：

npm install vite-tsconfig-paths --save-dev

2. 修改Vite配置：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import dts from "vite-plugin-dts";
import tsconfigPaths from 'vite-tsconfig-paths'; // 引入插件

export default defineConfig({
    plugins: [
        react(),
        dts({ include: ["src/**/*.tsx"] }),
        tsconfigPaths() // 添加插件
    ],
    // 其他配置保持不变...
});

这样Vite会自动同步tsconfig的paths作为别名，无需手动配置resolve.alias。

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