Vite应用动态导入失败时返回首页内容，如何解决？

实现方案 #

自定义元素用法 #

<html-include src="widgets/component-name.html"></html-include>

对应JavaScript类 #

class IncludeHTML extends HTMLElement {
    constructor() {
        super();
        this.innerHTML = 'Loading...';
        this.loadContent();
    }

    async loadContent() {
        const source = this.getAttribute('src');
        if (!source) {
            this.innerHTML = 'Sorry, unable to load widget';
            throw new Error('No src attribute given.');
        }
        const response = await fetch(source);
        if (response.status !== 200) {
            this.innerHTML = 'Sorry, unable to load widget';
            throw new Error(`Could not load resource: ${source}`);
        }
        const content = await response.text();
        this.innerHTML = content;
    }
}

window.customElements.define('html-include', IncludeHTML);

问题重现 #

当指定不存在的路径时：

<html-include src="widgets/made-up-path-that-does-not-exist.html"></html-include>

请求未返回预期的404错误，反而返回首页内容且状态码为200，导致自定义元素的错误处理逻辑无法触发。尝试配置vite.config.js中的appType为spa/mpa/custom均未解决问题。

解决思路 #

• 理解Vite SPA的路由 fallback 机制：SPA模式下，Vite默认会将所有未匹配的请求重定向到index.html（状态码200），用于支持前端路由。你的HTML文件请求被识别为未匹配路由，因此返回了首页。
• 配置Vite排除特定路径的fallback：在vite.config.js中通过rewrite规则，针对静态HTML文件的请求跳过SPA fallback：

import { defineConfig } from 'vite';

export default defineConfig({
  appType: 'spa',
  server: {
    rewrite: (path) => {
      // 对widgets目录下的HTML文件，不执行SPA fallback
      if (path.startsWith('/widgets/') && path.endsWith('.html')) {
        return path;
      }
      // 其他路径保持SPA fallback逻辑
      return '/index.html';
    }
  }
});

• 确保静态HTML资源被正确处理：在构建阶段配置assetsInclude，让Vite将HTML文件作为静态资源输出，避免被打包处理：

export default defineConfig({
  build: {
    assetsInclude: ['**/*.html']
  }
});

• 替换fetch为Vite原生静态资源导入：使用Vite的?raw后缀直接导入HTML文件，编译阶段即可检测文件是否存在，运行时也能正确捕获异常：

// 修改loadContent方法
async loadContent() {
  const source = this.getAttribute('src');
  if (!source) {
    this.innerHTML = 'Sorry, unable to load widget';
    throw new Error('No src attribute given.');
  }
  try {
    const content = await import(`${source}?raw`);
    this.innerHTML = content.default;
  } catch (err) {
    this.innerHTML = 'Sorry, unable to load widget';
    throw new Error(`Could not load resource: ${source}`);
  }
}

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