PAYATHON 2026

Vite 开发模式下静态资源 URL 出现重复 /static/ 如何解决

数据小陈

/static/static/ 是 Vite 开发服务器的 base: '/static/' 和入口路径 static/js/main.js 叠加后得到的结果,和 Django 的静态文件配置无关。开发模式下,django-vite 返回的是 Vite dev server 的地址,Vite 按“base + 源码相对路径”提供模块。你的源码相对路径已经以 static/ 开头,所以 URL 变成 /static/ 加上 static/js/main.js。生产模式走 manifest,由 Django 用 STATIC_URL 提供构建产物,通常不会出现这个重复。这个重复一般不影响运行,只是 URL 看起来不太顺眼。

为什么会重复

Vite 的 base 同时影响开发服务器 URL 和构建产物的公共路径。开发模式不经过 Django 的静态文件处理器,浏览器直接请求 http://localhost:5173/...。当配置为:

base: '/static/'

入口配置为:

main: resolve(import.meta.dirname, 'static/js/main.js')

Vite 开发服务器对这个模块的访问路径就是 /static/ 加上 static/js/main.js,得到:

/static/static/js/main.js

STATIC_URL = 'static/' 和 STATICFILES_DIRS 主要影响生产模式下 Django 如何提供构建后的文件,不会把这个开发模式 URL 自动“修正”成单层 /static/。

处理方式

方式一:接受它

只要页面能正常加载、HMR 正常、控制台没有 404,这个重复只出现在开发模式,不影响生产构建。你可以在浏览器 Network 面板确认 http://localhost:5173/static/static/js/main.js 确实返回 200。

方式二:开发模式把 Vite base 改为 /

如果只是想让开发模式 URL 干净一些,可以按 mode 切换 base:开发模式用 /,生产构建仍用 /static/。这样开发模式 URL 里只会出现一次 static:

import { defineConfig } from 'vite';
import { resolve } from 'path';

export default defineConfig(({ mode }) => ({
  base: mode === 'development' ? '/' : '/static/',
  build: {
    emptyOutDir: false,
    manifest: 'manifest.json',
    outDir: resolve(import.meta.dirname, 'assets'),
    rolldownOptions: {
      input: {
        main: resolve(import.meta.dirname, 'static/js/main.js'),
        style: resolve(import.meta.dirname, 'static/css/style.css'),
      },
      output: {
        entryFileNames: 'js/[name]-bundle.js',
        assetFileNames: 'css/[name]-bundle.css',
      },
    },
  },
}));

调整后开发模式应看到类似:

<script type='module' src='http://localhost:5173/static/js/main.js'></script>

改完后重启 Vite dev server,并清理浏览器缓存再查看。生产模式仍然使用 base: '/static/',避免构建后的 CSS/JS 内部引用资源时丢失 /static/ 前缀。

方式三:把源码目录移出 static/

也可以让 Vite 源码入口不再放在名为 static 的目录下,例如放到 frontend/js/main.js、frontend/css/style.css,构建输出仍然写到 Django 的静态目录。这样即使保留 base: '/static/',开发模式 URL 也不会出现两个 static。代价是需要同步修改 Vite input、模板中 {% vite_asset ... %} 使用的 manifest key,以及确认生产 manifest 能匹配。

注意事项

  • 不要只把模板里的 {% vite_asset 'static/js/main.js' %} 改成 {% vite_asset 'js/main.js' %}。如果 Vite input 和 manifest key 没有一起改,生产模式可能找不到对应资源。
  • STATIC_URL 建议写成 /static/ 这种带前导斜杠的形式,并与生产构建的 base 保持一致;如果项目当前用相对形式也能跑,至少确认最终请求路径符合预期。
  • STATICFILES_DIRS 指向构建输出目录,和 Vite 开发服务器无关。开发模式下静态资源由 Vite 提供,Django 不参与拼接这些 URL。
  • 如果使用 mode 切换 base,要检查 vite_hmr_client、HMR 连接和浏览器 Network 面板,确认没有因为 base 改变导致客户端路径异常。

备注:内容仅供参考。