Vue CLI 中 HTML 与静态资源的处理机制：模板注入、Preload/Prefetch 与 Asset Modules 全解

Vue CLI 中 HTML 与静态资源的处理机制模板注入、Preload/Prefetch 与 Asset Modules 全解【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli本文以 Vue CLI 官方指南「HTML 和静态资源」为核心系统讲解public/index.html模板机制、lodash 插值与环境变量注入、preload/prefetch 资源提示、多页应用构建以及相对路径资源与public目录两类静态资源的处理规则并结合vue/cli-service源码印证这些行为的底层实现帮助读者既能按文档完成实操又能理解配置生效的具体位置。HTML 部分Index 文件public/index.html 是一个构建模板public/index.html文件会被 html-webpack-plugin 当作模板处理在构建过程中资源链接构建产物的 JavaScript 和 CSS 文件会被自动注入。如果应用使用了 PWA 插件还会注入 manifest 与图标链接等 resource hint。从源码可以看到这一行为的完整实现在 app.js 中Vue CLI 注册了名为html的html-webpack-plugin并显式设置scriptLoading: defer让脚本以 defer 方式加载// packages/vue/cli-service/lib/config/app.js节选 const htmlOptions { title: api.service.pkg.name, scriptLoading: defer, templateParameters: (compilation, assets, assetTags, pluginOptions) { // enhance html-webpack-plugins built in template params return Object.assign({ compilation: compilation, webpackConfig: compilation.options, htmlWebpackPlugin: { tags: assetTags, files: assets, options: pluginOptions } }, resolveClientEnv(options, true /* raw */)) } }值得注意的是如果项目中不存在public/index.htmlVue CLI 会回退到内置的默认模板 index-default.html该模板结构极简div idapp/div加基础 meta保证任何项目都能被构建。创建项目时生成的 public/index.html 模板则展示了标准的用法形态link relicon href%% BASE_URL %%favicon.ico title%% htmlWebpackPlugin.options.title %%/title生成器模板中%%是对 lodash 插值语法的转义写法实际生成到项目里即为% %。插值lodash template 语法与客户端环境变量因为 index 文件被用作模板所以可以使用 lodash template 语法插入内容% VALUE %用来做不转义插值%- VALUE %用来做 HTML 转义插值% expression %用来描述 JavaScript 流程控制。除 html-webpack-plugin也可以直接在模板中使用。例如BASE_URL的用法link relicon href% BASE_URL %favicon.ico其底层机制在 resolveClientEnv.js 中它把process.env中以VUE_APP_为前缀的变量以及NODE_ENV收集起来并额外注入BASE_URL。而BASE_URL的值由 getBaseUrl.js 计算——它就是publicPath选项的值当publicPath为auto时为空字符串。这也解释了为什么publicPath配置变更后模板里的% BASE_URL %前缀会自动跟随更多说明可查阅 Vue CLI 配置文档publicPath、assetsDir、indexPath、filenameHashing等选项均在其中定义。Preload为初始渲染资源提前建立连接link relpreload是一种 resource hint用来指定页面加载后很快会被用到的资源。由于我们希望浏览器在开始主体渲染之前就尽早发起这些请求默认情况下一个 Vue CLI 应用会为所有初始化渲染需要的文件initial chunk 产物自动生成 preload 提示。按文档设计这些提示由vue/preload-webpack-plugin注入并且可以通过chainWebpack的config.plugin(preload)进行修改和删除典型配置为源码中被注册的选项rel: preload、include: initial、fileBlacklist: [/\.map$/, /hot-update\.js$/]即对 source map 与热更新文件不 preload。Prefetch空闲时间预取 async chunklink relprefetch是一种 resource hint用来告诉浏览器在页面加载完成后利用空闲时间提前获取用户未来可能会访问的内容。默认情况下一个 Vue CLI 应用会为所有作为 async chunk 生成的 JavaScript 文件即通过动态import()按需 code splitting 的产物自动生成 prefetch 提示。这些提示同样由vue/preload-webpack-plugin注入对应选项为rel: prefetch、include: asyncChunks并且可以通过chainWebpack的config.plugin(prefetch)进行修改和删除。示例// vue.config.js module.exports { chainWebpack: config { // 移除 prefetch 插件 config.plugins.delete(prefetch) // 或者 // 修改它的选项 config.plugin(prefetch).tap(options { options[0].fileBlacklist options[0].fileBlacklist || [] options[0].fileBlacklist.push(/myasyncRoute(.)?\.js$/) return options }) } }从源码结构看app.js 中单页模式下preload/prefetch插件的注册代码目前处于注释状态带有 FIXME 注释说明是在测试其与 html-webpack-plugin 4/5 及 webpack 5 的兼容性。因此在当前版本的仓库中更稳妥的做法是显式控制资源提示当 prefetch 插件被禁用时你可以通过 webpack 的内联注释手动选定要提前获取的代码区块import(/* webpackPrefetch: true */ ./someAsyncComponent.vue)webpack 的运行时会在父级区块被加载之后注入 prefetch 链接这一机制不依赖vue/preload-webpack-plugin在插件缺失时依然可用。提示Prefetch 链接将会消耗带宽。如果你的应用很大且有很多 async chunk而用户主要使用的是对带宽敏感的移动端那么你可能需要关掉 prefetch 链接并手动选择要提前获取的代码区块。不生成 index面向已有后端/SSR 的构建当基于已有的后端使用 Vue CLI 时你可能不需要生成index.html这样生成的资源可以用于一个服务端渲染的页面。这时可以向vue.config.js加入下列代码// vue.config.js module.exports { // 去掉文件名中的 hash filenameHashing: false, // 删除 HTML 相关的 webpack 插件 chainWebpack: config { config.plugins.delete(html) config.plugins.delete(preload) config.plugins.delete(prefetch) } }插件名html正对应源码中webpackConfig.plugin(html).use(HTMLPlugin, [htmlOptions])的注册名多页应用下则为html-页面名因此delete(html)能精准命中。然而文档并不推荐这样做因为硬编码的文件名不利于实现高效率的缓存控制硬编码的文件名也无法很好地进行 code-splitting代码分段因为无法用变化的文件名生成额外的 JavaScript 文件硬编码的文件名无法在现代模式下工作。正确的替代方案是使用indexPath选项见 配置文档将生成的 HTML 用作服务端框架的视图模板。其实现位于 app.js当options.indexPath不是默认的index.html时Vue CLI 会通过一个MovePlugin把构建出的index.html移动到indexPath指定的位置。构建多页应用MPA不是每个应用都需要是单页应用。Vue CLI 支持使用vue.config.js中的pages选项构建多页面应用构建好的应用会在不同的入口之间高效共享通用的 chunk 以获得最佳的加载性能。源码中 app.js 的多页逻辑印证了这一点每个页面默认模板为public/name.html、默认输出文件名为name.html每个页面默认引用[chunk-vendors, chunk-common, name]三组 chunk即所有页面共享 vendor 与 common 两个通用 chunksplitChunks配置app.js将node_modules依赖拆为chunk-vendors而把被至少两个初始 chunk 共同依赖的代码minChunks: 2拆为chunk-common并开启reuseExistingChunk这正是“入口之间高效共享通用 chunk”的来源页面的template支持 webpack loader 内联写法源码中会先template.replace(/^.!/, )去掉 loader 前缀再探测文件是否存在找不到专属模板时回退到public/index.html或默认模板。一个典型的多页配置形如// vue.config.js module.exports { pages: { index: { entry: src/index.js, title: App Index Page }, other: { entry: src/other.js, template: public/other.html, title: App Other Page } } }处理静态资源静态资源可以通过两种方式进行处理在 JavaScript 中被导入或在 template/CSS 中通过相对路径被引用。这类引用会被 webpack 处理放置在public目录下或通过绝对路径被引用。这类资源会被直接拷贝而不会经过 webpack 的处理。从相对路径导入进入 webpack 依赖图当你在 JavaScript、CSS 或*.vue文件中使用相对路径必须以.开头引用一个静态资源时该资源将会被包含进入 webpack 的依赖图中。在其编译过程中所有诸如img src...、background: url(...)和 CSSimport的资源 URL都会被解析为一个模块依赖。例如url(./image.png)会被翻译为require(./image.png)而img src./image.png将会被编译到h(img, { attrs: { src: require(./image.png) }})在其内部Vue CLI 通过 webpack 的 Assets Modules资产模块配置处理这些资源。这一点可以在 assets.js 中逐条看到 webpack rule 的定义规则名匹配文件类型输出子目录svg.svgasset/resourceimg/images.png / .jpg / .jpeg / .gif / .webp / .avifassetimg/media.mp4 / .webm / .ogg / .mp3 / .wav / .flac / .aacassetmedia/fonts.woff2 / .woff / .eot / .ttf / .otfassetfonts/注意两个细节SVG 被强制设为asset/resource源码注释明确写着 do not base64-inline SVGs即永远输出为独立文件而不内联asset类型未显式配置parser因此沿用 webpack 默认值——小于 8KiB 的资源会被内联为 Data URL以减少 HTTP 请求的数量。文件名的生成规则在 assets.js 的genAssetSubPath中const genAssetSubPath dir { return getAssetPath( options, ${dir}/[name]${options.filenameHashing ? .[hash:8] : }[ext] ) }即最终路径 assetsDir默认assets 子目录img/、media/、fonts/ 文件名 开启filenameHashing时的 8 位内容哈希 扩展名。哈希由 base.js 中设置的xxhash64算法生成。你可以通过chainWebpack调整内联文件的大小限制。例如下列代码会将内联图片资源限制设置为 4KiB// vue.config.js module.exports { chainWebpack: config { config.module .rule(images) .set(parser, { dataUrlCondition: { maxSize: 4 * 1024 // 4KiB } }) } }这里config.module.rule(images)正是命中上文 assets.js 中注册的images规则。URL 转换规则如果 URL 是一个绝对路径例如/images/foo.png它将会被保留不变如果 URL 以.开头它会作为一个相对模块请求被解释且基于你的文件系统中的目录结构进行解析如果 URL 以~开头其后的任何内容都会作为一个模块请求被解析。这意味着你甚至可以引用 Node 模块中的资源img src~some-npm-package/foo.png如果 URL 以开头它也会作为一个模块请求被解析。它的用处在于 Vue CLI 默认会设置一个指向projectRoot/src的别名。仅作用于模版中别名的来源在 base.jswebpackConfig.resolve.alias.set(, api.resolve(src))。由于是 webpack 的 resolve alias它天然对 JS 模块请求生效而在模板中让前缀 URL 走模块请求则依赖 vue-loader 对模板资源 URL 的转换因此文档标注该规则仅作用于模版。public 文件夹直接拷贝不经过 webpack任何放置在public文件夹的静态资源都会被简单地复制而不经过 webpack。你需要通过绝对路径来引用它们。其实现位于 app.jsVue CLI 用copy-webpack-plugin把整个public目录拷贝到输出目录noErrorOnMissing: true即public不存在也不报错并把当前使用的 HTML 模板自身加入ignore列表避免模板被二次拷贝。文档同时提醒推荐将资源作为模块依赖图的一部分导入因为它们会通过 webpack 的处理并获得如下好处脚本和样式表会被压缩且打包在一起从而避免额外的网络请求文件丢失会直接在编译时报错而不是到了用户端才产生 404 错误最终生成的文件名包含内容哈希因此你不必担心浏览器会缓存它们的老版本。public目录提供的是一个应急手段。当你通过绝对路径引用它时要留意应用将会部署到哪里。如果你的应用没有部署在域名的根部你需要为你的 URL 配置publicPath前缀在public/index.html或其它通过html-webpack-plugin用作模板的 HTML 文件中你需要通过% BASE_URL %设置链接前缀link relicon href% BASE_URL %favicon.ico在模板中你首先需要向你的组件传入基础 URLdata () { return { publicPath: process.env.BASE_URL } }然后img :src${publicPath}my-image.png何时使用 public 文件夹结合上文机制public目录适合以下三类场景你需要在构建输出中指定一个文件的名字webpack 产物名受[name]/[hash]规则控制无法随意指定而public中的文件名原样保留你有上千个图片需要动态引用它们的路径例如通过字符串拼接拼出文件名无法被静态分析进依赖图有些库可能和 webpack 不兼容这时你除了将其用一个独立的script标签引入没有别的选择。小结Vue CLI 的 HTML 与静态资源体系可以概括为两条主线HTML 侧由html-webpack-plugin lodash 模板 客户端环境变量注入完成html/preload/prefetch插件均可通过chainWebpack增删改静态资源侧由 webpack Asset Modulesimages/media/fonts/svg规则处理相对路径引用、由copy-webpack-plugin原样拷贝public目录。理解 app.js、assets.js 与 resolveClientEnv.js 这三个文件的分工就能在遇到模板插值不生效、资源 404、缓存失效或子路径部署等问题时快速定位到对应的配置开关。【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考