SvelteKit集成Hanko认证时导入hanko-elements遇'export'语法错误求助

核心问题 #

@teamhanko/hanko-elements是基于浏览器环境的Web Component库，依赖DOM API且仅支持浏览器端运行。SvelteKit默认开启SSR（服务端渲染），服务端尝试解析该库代码时会触发两个关键问题：

1. 库内包含仅能在浏览器中执行的逻辑，服务端环境无对应API支持
2. 库的纯ES模块格式在服务端CommonJS解析流程中出现语法兼容问题，直接抛出Unexpected token 'export'错误

全局关闭SSR能正常运行，本质是让代码完全在浏览器端执行，避开了服务端解析环节，但会影响整个应用性能，更优的做法是针对性处理：

解决方案1：局部关闭SSR（推荐） #

仅在使用Hanko组件的页面或布局中禁用SSR，而非全局关闭：

1. 在需要Hanko认证的页面目录下创建+page.ts，或其父布局目录下创建+layout.ts
2. 添加代码：

export const ssr = false;

这种方式仅让指定页面/布局走客户端渲染，其他页面保持SSR，平衡功能与性能。

解决方案2：动态导入Hanko模块 #

通过onMount钩子确保Hanko代码仅在浏览器DOM挂载后执行，避免服务端解析：

<script>
  import { onMount } from 'svelte';

  let hankoReady = false;

  onMount(async () => {
    // 动态导入仅在浏览器端触发
    const { register } = await import('@teamhanko/hanko-elements');
    // 替换为你的Hanko API地址
    await register('https://your-hanko-instance.com');
    hankoReady = true;
  });
</script>

{#if hankoReady}
  <hanko-auth />
{/if}

解决方案3：配置Vite跳过服务端解析 #

在svelte.config.js中修改Vite配置，让服务端不尝试解析Hanko模块：

import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

export default {
  preprocess: vitePreprocess(),
  kit: {
    vite: {
      ssr: {
        // 将Hanko标记为服务端不处理的外部依赖
        external: ['@teamhanko/hanko-elements']
      }
    }
  }
};

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