Vite开发服务器无法处理含#的公共资源文件名，求解决方案

云上老周

2026-6-13

Vite + React + TypeScript项目中含#字符的资源加载问题解决

问题背景

我的ViteJS+React+TypeScript项目里有一批文件名带#字符的资源（例如images/foo#2.png），开发服务器解析这类路径时出现异常：即便用encodeURIComponent()将#转成%23，资源依然无法正常加载。

重命名文件是最直接的解决方案，但这些文件来自作为子模块引入的第三方仓库，我无法直接修改；若要处理需fork仓库并添加构建脚本批量重命名，这种方案并不理想，因此想通过中间件等方式解决。

复现示例

示例代码

// main.js
document.querySelector('#app').innerHTML = `
  <div>
    <ul>
      vite.svg: <img src="vite.svg" /><br/>
      vite#2.svg 未编码: <img src="vite#2.svg" /><br/>
      vite#2.svg 编码后: <img src="${encodeURIComponent(
        'vite#2.svg'
      )}" />
    </ul>
  </div>
`;

文件夹结构

运行结果

解决方案

配置Vite服务器中间件修正请求路径
在vite.config.ts中添加自定义中间件，将请求URL中的%23（#的编码值）替换为实际的#字符，让服务器能正确匹配到对应的文件：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    async configureServer(server) {
      server.middlewares.use((req, res, next) => {
        // 替换请求URL中的%23为#
        if (req.url?.includes('%23')) {
          req.url = req.url.replace(/%23/g, '#');
        }
        next();
      });
    },
  },
});

前端正确编码资源路径
注意不要用encodeURIComponent()编码整个路径（会把/也转成%2F导致路径错误），只需单独编码文件名中的#字符：
```
// 正确写法：仅编码文件名中的#
const fileName = 'vite#2.svg';
const encodedFileName = fileName.replace(/#/g, '%23');
const imgSrc = `/${encodedFileName}`;
```