如何在SvelteKit中使用Node原生模块@zk-email/zk-regex-compiler

问题本质 #

@zk-email/zk-regex-compiler是基于Neon Rust构建的Node原生模块（.node格式），这类模块仅能在Node.js环境运行，无法直接在浏览器中执行。同时Vite默认无法识别.node文件格式，且SvelteKit的SSR机制会在服务器端预编译组件，导致直接导入时出现路径或语法解析错误。

分步解决方案 #

1. 基础配置：让Vite识别.node文件 #

首先修改vite.config.js，添加assetsInclude告诉Vite将.node文件视为资源：

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

export default defineConfig({
    plugins: [sveltekit()],
    assetsInclude: ['**/*.node'], // 新增：识别.node文件
    test: {
        include: ['src/**/*.{test,spec}.{js,ts}']
    }
});

2. 核心处理：区分运行环境 #

由于原生模块只能在Node.js环境执行，需根据使用场景选择不同方案：

场景一：在服务器端直接使用（推荐）

将模块导入到SvelteKit的服务器端文件中（如+page.server.js、+server.js或SSR的load函数），避免在客户端代码中直接引用：

// src/routes/+page.server.js
import compiler from "@zk-email/zk-regex-compiler";

export async function load() {
    // 在这里调用模块的方法
    const compiledResult = compiler.compile('your-regex-pattern');
    return { compiledResult };
}

在+page.svelte中通过服务器返回的数据使用结果：

<script>
    export let data;
</script>

<p>编译结果：{JSON.stringify(data.compiledResult)}</p>

场景二：客户端通过API调用（需前端触发编译时使用）

如果必须在客户端触发编译逻辑，需通过API路由封装服务器端的模块调用：

1. 创建API路由文件src/routes/api/compile/+server.js：

import compiler from "@zk-email/zk-regex-compiler";
import { json } from '@sveltejs/kit';

export async function POST({ request }) {
    const { regex } = await request.json();
    try {
        const compiled = compiler.compile(regex);
        return json({ success: true, compiled });
    } catch (error) {
        return json({ success: false, error: error.message }, { status: 500 });
    }
}

2. 在客户端+page.svelte中调用该API：

<script>
    async function handleCompile(regexInput) {
        const response = await fetch('/api/compile', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ regex: regexInput })
        });
        const result = await response.json();
        console.log(result);
    }
</script>

<input type="text" bind:value={regexPattern} placeholder="输入正则表达式" />
<button on:click={() => handleCompile(regexPattern)}>编译</button>

3. 修复vite-plugin-native的路径问题（可选） #

如果坚持使用vite-plugin-native，需解决模块路径解析错误：

• 检查node_modules/@zk-email/zk-regex-compiler下是否存在dist-native/index.node，若不存在，进入该模块目录执行构建命令：

cd node_modules/@zk-email/zk-regex-compiler
npm run build

• 或修改插件配置，指定模块的实际路径：

import native from 'vite-plugin-native';

export default defineConfig({
    plugins: [
        sveltekit(),
        native({
            target: 'esm',
            modules: [
                {
                    name: '@zk-email/zk-regex-compiler',
                    path: './index.node' // 指向模块根目录的index.node
                }
            ]
        })
    ]
});

注意：即使修复路径，原生模块依然无法在浏览器运行，仍需遵循前面的环境区分方案。

4. 禁用SSR（不推荐） #

若项目完全不需要SSR，可在svelte.config.js中禁用：

import adapter from '@sveltejs/adapter-auto';

export default {
    kit: {
        adapter: adapter(),
        ssr: false
    }
};

然后在客户端通过动态导入加载模块：

<script>
    let compiler;
    async function loadCompiler() {
        compiler = (await import("@zk-email/zk-regex-compiler")).default;
    }
</script>

<button on:click={loadCompiler}>加载编译器</button>

此方案会丢失SvelteKit的SSR优势，仅适合纯客户端项目。

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