Vite.js中HTML文件路径别名失效问题求助

问题描述 #

我在项目中配置了Vite路径别名，但HTML文件里的别名完全不生效。JS或SCSS中的别名能被转换（偶有例外），但HTML里的路径会直接报错，始终显示localhost/@/scripts/about.js，没有被转换为标准路径。

示例HTML代码（src/pages/about.html）：

<h2>Body of About</h2>
<script type="module" src="@/scripts/about.js"></script>

期望实现：HTML中的别名路径能自动转换为不含别名的标准路径。

技术栈：

• Vituum + PostHTML（也曾尝试Nunjucks）
• 原生HTML、JS、Scss

当前vite.config.js配置：

import { resolve } from 'path';

const projectRootDir = resolve(__dirname);

console.log(resolve(projectRootDir, '/src'));

export default {
  resolve: {
    alias: {
      '@': resolve(projectRootDir, 'src'),
      '@js': resolve(projectRootDir, 'src/scripts/'),
    },
  },
};

解决方法 #

Vite默认的别名配置仅处理JS、CSS等模块文件，不会解析HTML中的资源路径。要让HTML识别别名，可通过以下几种方式实现：

1. 启用Vituum内置的HTML路径解析 #

Vituum自带HTML路径解析能力，只需在配置中开启并同步别名：

修改vite.config.js：

import { resolve } from 'path';

const projectRootDir = resolve(__dirname);

export default {
  resolve: {
    alias: {
      '@': resolve(projectRootDir, 'src'),
      '@js': resolve(projectRootDir, 'src/scripts/'),
    },
  },
  vituum: {
    html: {
      resolvePaths: true, // 开启HTML路径解析
      aliases: {
        '@': resolve(projectRootDir, 'src') // 同步别名配置
      }
    }
  }
};

2. 使用PostHTML别名插件 #

如果内置方案不生效，可借助posthtml-path-alias插件处理：

第一步，安装插件：

npm install posthtml-path-alias --save-dev

第二步，在vite.config.js中配置PostHTML：

import { resolve } from 'path';
import posthtmlAlias from 'posthtml-path-alias';

const projectRootDir = resolve(__dirname);

export default {
  resolve: {
    alias: {
      '@': resolve(projectRootDir, 'src'),
      '@js': resolve(projectRootDir, 'src/scripts/'),
    },
  },
  vituum: {
    html: {
      plugins: [
        posthtmlAlias({
          alias: {
            '@': resolve(projectRootDir, 'src')
          },
          root: projectRootDir
        })
      ]
    }
  }
};

3. 用Nunjucks全局变量替代别名 #

若使用Nunjucks模板，可定义全局变量拼接路径：

修改vite.config.js添加全局变量：

import { resolve } from 'path';

const projectRootDir = resolve(__dirname);
const srcPath = resolve(projectRootDir, 'src');

export default {
  resolve: {
    alias: {
      '@': srcPath,
      '@js': resolve(srcPath, 'scripts/'),
    },
  },
  vituum: {
    nunjucks: {
      globals: {
        srcUrl: '/src' // 根据实际输出路径调整
      }
    }
  }
};

在HTML中使用变量：

<script type="module" src="{{ srcUrl }}/scripts/about.js"></script>

注意：修改配置后需重启开发服务器，确保配置生效。同时检查输出路径，避免相对路径错误。

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