SvelteKit使用Vite构建时static目录图片未被打包如何解决

问题基础信息 #

• 技术栈：SvelteKit + Vite
• 异常文件：存放在项目static文件夹下的trashCan.svg
• 复现规则：本地执行生产构建即可稳定复现，构建完成后目标图片不存在于最终输出产物中
• 完整构建日志：

> tailwind-svelte@0.0.1 build
> vite build
 
vite v2.9.13 building for production...
✓ 14 modules transformed.
.svelte-kit/output/client/_app/immutable/manifest.json                            1.21 KiB
.svelte-kit/output/client/_app/immutable/layout.svelte-85bee214.js                0.53 KiB / gzip: 0.35 KiB
.svelte-kit/output/client/_app/immutable/error.svelte-b3f7066d.js                 1.56 KiB / gzip: 0.75 KiB
.svelte-kit/output/client/_app/immutable/pages/index.svelte-46e2bffd.js           3.68 KiB / gzip: 1.80 KiB
.svelte-kit/output/client/_app/immutable/start-5d947e25.js                        22.66 KiB / gzip: 8.58 KiB
.svelte-kit/output/client/_app/immutable/assets/pages/index.svelte-74cec484.css   6.91 KiB / gzip: 1.84 KiB
.svelte-kit/output/client/_app/immutable/chunks/index-7fb2b6d1.js                 7.15 KiB / gzip: 2.91 KiB
vite v2.9.13 building SSR bundle for production...
✓ 12 modules transformed.
Generated an empty chunk: "hooks"
.svelte-kit/output/server/manifest.json                        1.17 KiB
.svelte-kit/output/server/index.js                             74.35 KiB
.svelte-kit/output/server/entries/fallbacks/layout.svelte.js   0.24 KiB
.svelte-kit/output/server/entries/fallbacks/error.svelte.js    0.72 KiB
.svelte-kit/output/server/entries/pages/index.svelte.js        14.22 KiB
.svelte-kit/output/server/chunks/index-5f038599.js             2.31 KiB
.svelte-kit/output/server/chunks/hooks-1c45ba0b.js             0.00 KiB
 
Run npm run preview to preview your production build locally.
(node:89537) ExperimentalWarning: buffer.Blob is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

核心成因 #

SvelteKit + Vite构建时处理static目录资源有明确规则，漏打包通常由以下几种原因导致：

• 引用路径错误：static目录下的文件必须以根绝对路径引用，也就是路径以/开头，直接映射static下的文件结构。如果写了./trashCan.svg这类相对路径，或者带static/前缀的路径（比如/static/trashCan.svg），开发环境可能因代理规则凑巧加载成功，但构建阶段Vite无法识别该资源属于static目录，不会将其复制到产物中。
• 文件名大小写不匹配：如果代码中写的文件名和实际存储的文件名大小写不一致，在Windows、macOS这类大小写不敏感的本地文件系统中开发时可以正常加载，但Vite构建时的静态路径匹配是大小写敏感的，匹配不到对应文件就不会输出。
• 动态路径拼接：如果引用路径是通过字符串拼接动态生成的（比如`/trashCan${suffix}.svg`），Vite的静态分析无法扫描到具体依赖的文件，不会将对应资源加入构建列表。
• 静态资源目录配置被修改：如果svelte.config.js中自定义修改了kit.files.assets配置项，默认的static目录不再作为静态资源输出目录，目录下的文件自然不会进入构建产物。

修复方案 #

按优先级依次排查修复：

1. 修正引用路径：trashCan.svg放在static根目录的话，所有引用位置统一写为/trashCan.svg，不要加static前缀，不要写相对路径。
2. 核对文件名大小写：确保代码中引用的文件名和本地实际文件名的大小写完全一致，不要出现驼峰、小写混用的情况。
3. 替换动态引用：如果是动态拼接的路径，要么改成静态字符串显式引用，要么把图片移到src/lib/assets目录下，通过import trashCan from '$lib/assets/trashCan.svg'的方式引入，这种引入方式Vite会直接识别为依赖，不会出现漏打包问题。
4. 检查配置：打开svelte.config.js，确认kit.files.assets配置没有被错误修改，保持默认值static即可。

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