SvelteKit项目中Vite自定义插件无法使用$lib/$env别名问题排查

我在SvelteKit项目里常用$lib、$env这类路径别名导入模块，但写了自定义Vite插件后，想在插件里沿用这些别名导入环境变量和JS文件，配置完vite.config.js和socketHandler.js后，执行npm run dev出现模块找不到的错误。

相关代码 #

vite.config.js #

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import path from 'path';
import socketHandler from './src/lib/server/socketHandler/socketHandler.js';

const webSocketServer = {
    name: 'webSocketServer',
    configureServer(server) {
        if (!server.httpServer) return;
        socketHandler(server.httpServer);
    }
}

export default defineConfig({
    plugins: [sveltekit() , webSocketServer()],
        resolve: {
            alias: {
              '$lib': path.resolve(__dirname, './src/lib'),
              '$env': path.resolve(__dirname, '.'),
            },
          },
    
});

socketHandler.js #

import { Server } from 'socket.io';
import login from '$lib/login.js';
import {DB_PASSWORD} from '$env/static/private';
import disconnect from '$lib/disconnect.js';
// other imports...

global.userCode = {};

export default function socketHandler(server) {
    const db_pass=DB_PASSWORD;
    const io = new Server(server);

    const onConnection = (socket) => {
        reconnect(io, socket); 
        disconnect(io, socket);
        login(io, socket); 
        orderRequest(io, socket);
        // ...
    }
    
    io.on("connection", onConnection);
}

错误信息 #

failed to load config from C:\home\lcare_renewal\vite.config.js
error when starting dev server:
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '$lib' imported from C:\home\lcare_renewal\vite.config.js.timestamp-1727503166699-f59eaa69482cd.mjs
    at new NodeError (node:internal/errors:405:5)
    at packageResolve (node:internal/modules/esm/resolve:890:9)
    at moduleResolve (node:internal/modules/esm/resolve:939:20)
    at defaultResolve (node:internal/modules/esm/resolve:1132:11)
    at nextResolve (node:internal/modules/esm/loader:163:28)
    at ESMLoader.resolve (node:internal/modules/esm/loader:835:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40)
    at link (node:internal/modules/esm/module_job:76:36)

核心问题 #

1. Vite的别名配置仅在Vite处理的应用代码中生效，你在vite.config.js里直接导入socketHandler.js的操作是由Node.js的ES模块加载器处理的，Node不认识$lib、$env这些别名，因此找不到模块。
2. 手动配置的$env别名完全错误：SvelteKit的$env/static/private是框架内置的虚拟模块，不是对应项目根目录的物理文件，手动映射会覆盖框架的内置逻辑，导致环境变量无法正常加载。

解决步骤 #

1. 改用Vite的ssrLoadModule加载含别名的文件 #

把socketHandler的导入移到插件的configureServer函数内部，用Vite提供的server.ssrLoadModule方法加载，让Vite处理别名解析：

修改后的vite.config.js：

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import path from 'path';

const webSocketServer = {
    name: 'webSocketServer',
    async configureServer(server) {
        if (!server.httpServer) return;
        // 用Vite的ssrLoadModule加载，让Vite处理别名解析
        const { default: socketHandler } = await server.ssrLoadModule('./src/lib/server/socketHandler/socketHandler.js');
        socketHandler(server.httpServer);
    }
}

export default defineConfig({
    plugins: [sveltekit(), webSocketServer], // 注意：插件是对象，不需要加()调用
    resolve: {
        alias: {
            '$lib': path.resolve(__dirname, './src/lib'),
            // 删掉$env的手动配置，SvelteKit会自动处理
        },
    },
});

2. 移除无效的$env别名配置 #

直接删除resolve.alias中的$env映射，保留SvelteKit内置的虚拟模块逻辑即可。

3. 保留socketHandler中的原有导入 #

socketHandler.js里的$lib和$env导入无需修改，现在通过ssrLoadModule加载后，Vite会结合SvelteKit的内置规则和你配置的$lib别名完成解析。

额外注意点 #

• 插件的configureServer方法使用异步操作时，必须加上async关键字，避免加载顺序问题。
• 自定义插件是对象类型，不需要加()调用，你之前的webSocketServer()写法会直接执行对象，引发额外错误。

内容的提问来源于stack exchange，提问作者한테로