前端Vite配置规范书

前端Vite配置规范书一、配置文件基础规范1.1文件命名与结构Vite配置文件统一命名为vite.config.js或vite.config.ts，优先使用TypeScript版本以获得类型提示。配置文件应遵循模块化结构，将不同功能的配置项拆分为独立函数或模块，提高可读性和可维护性。//vite.config.tsimport{defineConfig}from'vite'importvuefrom'@vitejs/plugin-vue'import{resolve}from'path'//路径解析函数constpathResolve=(dir:string)=>resolve(__dirname,dir)exportdefaultdefineConfig({plugins:[vue()],resolve:{alias:{'@':pathResolve('src'),'@components':pathResolve('src/components')}}})1.2环境变量管理所有环境变量应定义在.env、.env.development、.duction等文件中，避免在代码中硬编码敏感信息。环境变量命名需以VITE_开头，确保能被Vite正确识别。#.ductionVITE_APP_TITLE=生产环境应用VITE_API_BASE_URL=VITE_APP_VERSION=1.0.0在代码中通过import.meta.env访问环境变量：console.log(import.meta.env.VITE_APP_TITLE)二、开发服务器配置规范2.1基础服务配置开发服务器端口统一设置为3000，若端口冲突可依次尝试3001、3002。开启open选项，使服务启动时自动打开浏览器。exportdefaultdefineConfig({server:{port:3000,open:true,host:''//允许外部访问}})2.2代理配置前端开发中常需跨域访问后端API，应统一配置代理规则，避免在代码中添加跨域标识。代理规则需清晰注释，标明目标地址和用途。exportdefaultdefineConfig({server:{proxy:{//接口代理'/api':{target:'http://localhost:8080',changeOrigin:true,rewrite:(path)=>path.replace(/^\/api/,'')},//静态资源代理'/assets':{target:'',changeOrigin:true}}}})三、构建配置规范3.1输出目录与资源命名构建输出目录统一为dist，静态资源文件名需包含哈希值以防止浏览器缓存冲突。图片、字体等资源文件命名采用小写字母加中划线的格式，如user-avatar.png。exportdefaultdefineConfig({build:{outDir:'dist',assetsDir:'static',assetsInlineLimit:4096,//小于4KB的资源内联rollupOptions:{output:{chunkFileNames:'static/js/[name]-[hash].js',entryFileNames:'static/js/[name]-[hash].js',assetFileNames:'static/[ext]/[name]-[hash].[ext]'}}}})3.2代码分割与优化开启代码分割功能，将第三方库和业务代码分离，提高页面加载速度。对大型依赖包如lodash、moment.js进行按需引入配置。exportdefaultdefineConfig({build:{rollupOptions:{output:{manualChunks:{//将Vue相关库打包成单独chunkvue:['vue','vue-router','pinia'],//将UI组件库打包成单独chunkelementPlus:['element-plus']}}}}})3.3环境特定配置根据不同环境配置不同的构建选项，生产环境开启代码压缩和混淆，开发环境保留源代码格式以便调试。exportdefaultdefineConfig(({mode})=>{constisProduction=mode==='production'return{build:{minify:isProduction?'terser':false,sourcemap:!isProduction}}})四、插件配置规范4.1核心插件管理Vite官方插件如@vitejs/plugin-vue、@vitejs/plugin-vue-jsx应使用最新稳定版本，避免使用beta或alpha版本。插件配置应集中管理，便于统一维护。importvuefrom'@vitejs/plugin-vue'importvueJsxfrom'@vitejs/plugin-vue-jsx'exportdefaultdefineConfig({plugins:[vue({template:{compilerOptions:{//自定义全局组件前缀isCustomElement:(tag)=>tag.startsWith('my-')}}}),vueJsx()]})4.2第三方插件规范引入第三方插件时需评估其稳定性和维护状态，优先选择下载量高、更新频繁的插件。插件配置应添加详细注释，说明用途和关键参数。import{viteMockServe}from'vite-plugin-mock'exportdefaultdefineConfig({plugins:[viteMockServe({mockPath:'mock',//mock文件目录localEnabled:true,//开发环境启用prodEnabled:false//生产环境禁用})]})五、路径解析与别名配置5.1别名统一管理配置路径别名简化模块导入，统一使用@指向src目录，其他常用目录如components、utils也应配置别名。exportdefaultdefineConfig({resolve:{alias:{'@':resolve(__dirname,'src'),'@components':resolve(__dirname,'src/components'),'@utils':resolve(__dirname,'src/utils'),'@styles':resolve(__dirname,'src/styles')}}})在tsconfig.json中同步配置别名以获得TypeScript类型支持：{"compilerOptions":{"baseUrl":".","paths":{"@/*":["src/*"],"@components/*":["src/components/*"]}}}5.2扩展名省略规则配置扩展名省略列表，优先省略.vue、.js、.ts等常用扩展名，减少代码中的冗余字符。exportdefaultdefineConfig({resolve:{extensions:['.mjs','.js','.ts','.jsx','.tsx','.json','.vue']}})六、CSS预处理规范6.1预处理器选择优先使用Sass/SCSS作为CSS预处理器，统一缩进风格为2空格。全局样式文件命名为global.scss，放置在src/styles目录下。//src/styles/global.scss$primary-color:#409eff;$border-radius:4px;body{margin:0;padding:0;font-family:-apple-system,BlinkMacSystemFont,'SegoeUI',Roboto,Oxygen,Ubuntu,Cantarell,sans-serif;}.container{max-width:1200px;margin:0auto;padding:020px;}6.2CSSModules配置启用CSSModules避免样式冲突，模块文件命名采用.module.scss格式。在Vue组件中通过scoped属性或CSSModules实现样式隔离。<template><div:class="$style.button">按钮</div></template><stylemodule>.button{padding:8px16px;background-color:$primary-color;border-radius:$border-radius;color:white;}</style>七、性能优化配置7.1依赖预构建Vite默认会预构建依赖包，可通过optimizeDeps配置手动指定需要预构建的依赖，特别是那些非ES模块格式的包。exportdefaultdefineConfig({optimizeDeps:{include:['lodash-es','moment'],exclude:['some-es-module-package']}})7.2图片资源优化使用vite-plugin-imagemin插件压缩图片资源，配置合理的压缩参数平衡图片质量和文件大小。importviteImageminfrom'vite-plugin-imagemin'exportdefaultdefineConfig({plugins:[viteImagemin({gifsicle:{optimizationLevel:7,interlaced:false},optipng:{optimizationLevel:7},mozjpeg:{quality:80},pngquant:{quality:[0.8,0.9],speed:4}})]})7.3代码压缩与混淆生产环境开启Terser压缩，配置压缩参数移除console.log和debugger语句，减少代码体积。exportdefaultdefineConfig({build:{minify:'terser',terserOptions:{compress:{drop_console:true,drop_debugger:true}}}})八、多页面应用配置8.1入口文件配置多页面应用需配置build.rollupOptions.input指定多个入口文件，每个页面对应一个HTML模板。exportdefaultdefineConfig({build:{rollupOptions:{input:{main:resolve(__dirname,'index.html'),admin:resolve(__dirname,'admin.html')}}}})8.2页面模板规范每个HTML模板应包含基本的页面结构，使用<%=VITE_APP_TITLE%>注入环境变量，确保页面标题动态化。<!--admin.html--><!DOCTYPEhtml><htmllang="zh-CN"><head><metacharset="UTF-8"><title><%=VITE_APP_TITLE%>-管理后台</title></head><body><divid="app"></div><scripttype="module"src="/src/admin/main.ts"></script></body></html>九、部署与CI/CD配置9.1构建产物规范构建产物应包含完整的HTML、CSS、JS文件和静态资源，确保能直接部署到静态服务器。生成build-info.json文件记录构建信息，便于问题排查。//在vite.config.ts中添加构建钩子import{writeFileSync}from'fs'exportdefaultdefineConfig({build:{onEnd:()=>{constbuildInfo={timestamp:newDate().toISOString(),version:process.env.VITE_APP_VERSION,commit:process.env.GIT_COMMIT_HASH}writeFileSync(resolve(__dirname,'dist/build-info.json'),JSON.stringify(buildInfo,null,2))}}})9.2Docker部署配置提供Dockerfile模板，支持容器化部署。使用多阶段构建减小镜像体积，生产环境使用Nginx作为Web服务器。#构建阶段FROMnode:18-alpineasbuilderWORKDIR/appCOPYpackage*.json./RUNnpmciCOPY..RUNnpmrunbuild#生产阶段FROMnginx:alpineCOPY--from=builder/app/dist/usr/share/nginx/htmlCOPYnginx.conf/etc/nginx/nginx.confEXPOSE80CMD["nginx","-g","daemonoff;"]十、配置文件版本控制10.1忽略文件规范在.gitignore中添加以下规则，避免提交敏感信息和构建产物：#环境变量文件.env.env.local.env.*.local#构建产物distdist-ssr#日志文件npm-debug.log*yarn-debug.log*#编辑器目录.vscode.idea10.2配置变更流程修改Vite配置文件需提交代码评审，评审通过后方可合并到主分支。配置变更需在CHANGELOG.md中记录，说明变更内容和影响范围。##[1.2.0]-2024-01-15###Changed-升级Vite到5.0版本-修改开发服务器端口为3000-新增图片压缩插件配置十一、错误处理与日志11.1开发环境错误提示开发环境开启clearScreen选项，保持控制台整洁。配置server.hmr.overlay显示错误覆盖层，便于快速定位问题。exportdefaultdefineConfig({server:{hmr:{overlay:true}},clearScreen:true})11.2生产环境错误监控生产环境接入Sentry等错误监控系统，配置SourceMap上传便于错误定位。import{sentryVitePlugin}from'@sentry/vite-plugin'exportdefaultdefineConfig({plugins:[sentryVitePlugin({org:'your-org',project:'your-project',authToken:process.env.SENTRY_AUTH_TOKEN})]})十二、兼容性配置12.1ES版本兼容配置build.target指定目标浏览器ES版本，默认使用modules支持现代浏览器，如需兼容旧版浏览器可设置为es2015。exportdefaultdefineConfig({build:{target:'es2015'}})12.2polyfill配置使用@vitejs/plugin-legacy插件为旧版浏览器提供polyfill，配置需要兼容的浏览器版本。importlegacyfrom'@vitejs/plugin-legacy'exportdefaultdefineConfig({plugins:[legacy({targets:['defaults','notIE11'],additionalLegacyPolyfills:['regenerator-runtime/runtime']})]})十三、安全配置13.1CSP配置配置内容安全策略(CSP)防止XSS攻击，在HTML模板中添加meta标签或通过Nginx配置。<metahttp-equiv="Content-Security-Policy"content="default-src'self';script-src'self''unsafe-inline';style-src'self''unsafe-inline'">13.2依赖安全扫描定期使用npmaudit或snyk扫描依赖包安全漏洞，及时更新存在安全问题的依赖。npmauditfixsnyktestsnykmonitor十四、配置文件注释规范14.1关键配置注释所有非默认配置项都应添加注释，说明配置目的、参数含义和注意事项。注释应简洁明了，避免冗余信息。exportdefaultdefineConfig({server:{proxy:{//代理API请求到后端服务器//开发环境解决跨域问题，生产环境由Nginx处理'/api':{target:'http://localhost:8080',changeOrigin:true,//必须设置为true，否则请求头中的host会是Vite服务器地址rewrite:(path)=>path.replace(/^\/api/,'')//移除路径中的/api前缀}}}})14.2复杂配置文档对于复杂的配置逻辑，如自定义插件、多环境切换等，应在项目文档中详细说明，包括配置背景、使用方法和示例代码。十五、配置文件审核与维护15.1定期审核机制每季度对Vite配置文件进行一次全面审核，检查配置项是否符合最新规范，移除不再使用的配置，更新过时的插件版本。15.2版本升级流程升级Vite或插件版本需遵循以下流程：在测试分支进行版本升级运行所有单元测试和集成测试进行回归测试确保功能正常提交代码评审并记录变更内容合并到主分支并发布新版本十六、附录：常用配置模板16.1Vue3项目基础配置import{defineConfig}from'vite'importvuefrom'@vitejs/plugin-vue'import{resolve}from'path'constpathResolve=(dir:string)=>resolve(__dirname,dir)exportdefaultdefineConfig({plugins:[vue()],resolve:{alias:{'@':pathResolve('src'),'@components':pathResolve('src/components'),'@utils':pathResolve('src/utils')},extensions:['.mjs','.js','.ts','.jsx','.tsx','.json','.vue']},server:{port:3000,open:true,proxy:{'/api':{target:'http://localho