资讯详情

深入了解 · 专业解读

Vite 0.1.7：构建追踪与资源映射新升级

发布时间：2026/6/21 23:46:21
Vite 0.1.7：构建追踪与资源映射新升级 版本0.1.7 | 协议MIT | 依赖Vite 5.0.0 8.0.0写在前面v0.1.7 的主题是让构建产物可追踪让资源映射可编程。在 SPA/MPA 应用中构建产物经过 hash 命名后原始文件名与实际输出路径之间的映射关系难以获取。v0.1.7 新增的assetManifest插件在构建完成后自动扫描输出目录生成资源映射清单manifest.json支持 Vite 标准、Webpack 兼容和自定义三种输出格式并可按入口分组或将清单注入为运行时全局变量实现从构建到运行时的完整资源追踪链路。本版重点能力一句话说明你需要做什么assetManifest资源清单生成构建后自动生成资源映射清单支持三种格式、入口分组和运行时注入新增配置assetManifest按入口分组将资源按入口点分类区分 JS/CSS/其他文件新增配置assetManifest运行时注入将清单以全局变量注入 HTML运行时可直接访问资源映射新增配置升级方式修改devDependencies中版本号为^0.1.7。无 Breaking Changes完全向后兼容。一、5 分钟快速上手1.1 安装与最小配置{devDependencies:{meng-xi/vite-plugin:^0.1.7}}import{assetManifest}frommeng-xi/vite-pluginexportdefaultdefineConfig({plugins:[assetManifest()]})1.2 立刻看到效果构建完成后dist/manifest.json自动生成{version:1.0,timestamp:2026-06-07T15:30:00.000Z,publicPath:/,assets:{index.html:/index.html,assets/index-abc123.js:/assets/index-abc123.js,assets/index-def456.css:/assets/index-def456.css,assets/logo-ghi789.png:/assets/logo-ghi789.png}}1.3 运行时访问清单启用injectRuntime后在浏览器中可直接访问资源映射// vite.config.tsassetManifest({injectRuntime:true,runtimeGlobalName:__ASSET_MANIFEST__})// 运行时代码constmanifestwindow.__ASSET_MANIFEST__console.log(manifest.assets[assets/logo-ghi789.png])// /assets/logo-ghi789.png二、核心能力assetManifest 资源清单生成2.1 三种输出格式Vite 标准格式默认键为原始资源路径值为带 publicPath 的输出路径并包含版本号和时间戳元信息{version:1.0,timestamp:2026-06-07T15:30:00.000Z,publicPath:/,assets:{index.html:/index.html,assets/index-abc123.js:/assets/index-abc123.js}}Webpack 兼容格式模拟 Webpack ManifestPlugin 的输出结构包含entries和assets两个字段方便从 Webpack 迁移的项目使用{entries:[{name:main,files:[/assets/index-abc123.js,/assets/index-def456.css]}],assets:{index.html:/index.html,assets/index-abc123.js:/assets/index-abc123.js}}自定义格式通过customFormatter回调函数完全控制输出结构assetManifest({outputFormat:custom,customFormatter:assets{// 只输出 JS 和 CSS 文件constfilteredObject.fromEntries(Object.entries(assets).filter(([key])key.endsWith(.js)||key.endsWith(.css)))return{files:filtered,generatedAt:newDate().toISOString()}}})2.2 按入口分组启用groupByEntry后清单中会包含按入口点分组的资源信息将每个入口关联的 JS、CSS 和其他资源文件分类整理assetManifest({outputFormat:vite,groupByEntry:true})生成的清单会额外包含groups字段{version:1.0,timestamp:2026-06-07T15:30:00.000Z,publicPath:/,assets:{...:...},groups:[{entry:main,assets:{js:[/assets/index-abc123.js],css:[/assets/index-def456.css],other:[/assets/logo-ghi789.png]}},{entry:vendor,assets:{js:[/assets/vendor-xyz999.js],css:[],other:[]}}]}2.3 运行时注入启用injectRuntime后插件会在构建完成后将资源映射表以script标签的形式注入到输出目录中的所有 HTML 文件的/head标签前assetManifest({injectRuntime:true,runtimeGlobalName:__ASSET_MANIFEST__})注入后的 HTMLheadscriptwindow.__ASSET_MANIFEST__{assets:{index.html:/index.html,assets/index-abc123.js:/assets/index-abc123.js}}/script!-- 其他 head 内容 --/head运行时即可通过全局变量访问constmanifestwindow.__ASSET_MANIFEST__constjsFilesObject.keys(manifest.assets).filter(keykey.endsWith(.js))2.4 文件过滤通过includeExtensions、excludeExtensions和excludePaths灵活控制清单包含的文件assetManifest({// 只包含 JS 和 CSS 文件includeExtensions:[.js,.css],// 排除 source map 和压缩文件默认行为excludeExtensions:[.map,.gz,.br],// 排除特定路径excludePaths:[assets/icons/,assets/sprites/]})优先级excludePathsexcludeExtensionsincludeExtensions。2.5 公共路径前缀publicPath会自动添加到所有资源路径前适配 CDN 部署场景assetManifest({publicPath:https://cdn.example.com/})输出结果{assets:{assets/index-abc123.js:https://cdn.example.com/assets/index-abc123.js}}2.6 实例方法插件实例提供三个方法供外部访问清单数据constpluginassetManifest({outputFormat:vite,groupByEntry:true})// 构建完成后...constassetMapplugin.pluginInstance?.getAssetMap?.()// 资源映射表constmanifestplugin.pluginInstance?.getManifest?.()// 完整清单数据constgroupsplugin.pluginInstance?.getGroups?.()// 入口分组信息2.7 冲突检测构建资源映射表时如果出现原始路径冲突多个文件映射到同一个输出路径插件会自动输出警告日志帮助发现潜在的构建配置问题。三、配置选项选项类型默认值描述outputFormatvite|webpack|customvite清单输出格式outputFilestringmanifest.json清单输出文件名相对于构建输出目录includeExtensionsstring[][]包含的文件扩展名为空则包含所有publicPathstring/公共路径前缀injectRuntimebooleanfalse是否将清单注入为运行时全局变量runtimeGlobalNamestring__ASSET_MANIFEST__运行时全局变量名称customFormatterCustomFormatter|nullnull自定义格式化器仅custom格式时生效groupByEntrybooleanfalse是否按入口分组资源excludeExtensionsstring[][.map, .gz, .br]排除的文件扩展名excludePathsstring[][]排除的路径模式列表继承BasePluginOptions通用配置enabled、verbose、errorStrategy。四、类型导出类型描述AssetManifestOptions插件配置选项ManifestOutputFormat清单输出格式类型AssetMap资源映射表键为原始路径值为输出路径AssetGroup按入口分组的资源信息AssetManifestResultVite 格式的完整清单数据WebpackEntryAssetWebpack 格式的入口资源信息WebpackManifestOutputWebpack 格式的完整清单输出CustomFormatter自定义格式化器函数类型五、实战场景5.1 CDN 预加载import{defineConfig}fromviteimport{assetManifest}frommeng-xi/vite-pluginexportdefaultdefineConfig({plugins:[assetManifest({outputFormat:vite,publicPath:https://cdn.example.com/,injectRuntime:true,runtimeGlobalName:__ASSET_MANIFEST__})]})运行时根据清单预加载关键资源constmanifestwindow.__ASSET_MANIFEST__ Object.values(manifest.assets).filter(pathpath.endsWith(.js)).forEach(path{constlinkdocument.createElement(link)link.relprefetchlink.hrefpath document.head.appendChild(link)})5.2 SSR 资源映射import{assetManifest}frommeng-xi/vite-pluginexportdefaultdefineConfig({plugins:[assetManifest({outputFormat:vite,groupByEntry:true})]})SSR 服务端读取清单文件根据入口名获取对应的 JS/CSS 文件路径importmanifestfrom./dist/manifest.jsonfunctiongetEntryAssets(entryName:string){constgroupmanifest.groups?.find(gg.entryentryName)return{scripts:group?.assets.js??[],styles:group?.assets.css??[]}}5.3 Webpack 迁移兼容import{assetManifest}frommeng-xi/vite-pluginexportdefaultdefineConfig({plugins:[assetManifest({outputFormat:webpack})]})生成的清单与 Webpack ManifestPlugin 格式兼容无需修改下游消费代码。5.4 uni-app 项目import{assetManifest}from./uni_modules/vite-plugin/js_sdk/index.mjsexportdefaultdefineConfig({plugins:[uni(),assetManifest({outputFormat:vite,outputFile:manifest.json,injectRuntime:true,groupByEntry:true,enabled:process.env.NODE_ENVproduction})]})六、子路径导出变更子路径变更内容meng-xi/vite-plugin/plugins/asset-manifest新增assetManifest函数及所有类型导出七、迁移指南从 v0.1.6 升级到 v0.1.71. 启用资源清单生成可选import{assetManifest}frommeng-xi/vite-pluginexportdefaultdefineConfig({plugins:[assetManifest()]})2. 按需配置高级功能assetManifest({outputFormat:vite,// 或 webpack、custompublicPath:/,// CDN 场景设为 CDN 域名injectRuntime:true,// 运行时访问清单groupByEntry:true,// 按入口分组excludeExtensions:[.map,.gz,.br]// 排除不需要的文件})3. 子路径独立导入import{assetManifest}frommeng-xi/vite-plugin/plugins/asset-manifestimporttype{AssetManifestOptions,AssetMap}frommeng-xi/vite-plugin/plugins/asset-manifest本文基于meng-xi/vite-plugin0.1.7版本撰写所有代码示例均来自实际源码。

相关新闻