企业官网建设流程全解析

版本：0.1.6 | 协议：MIT | 依赖：Vite >=5.0.0 <8.0.0

写在前面

v0.1.6 的主题是：让自动导入更智能，让路由导航更安全，让工具层更实用。

v0.1.5 引入的autoImport插件需要逐一列举要导入的 API 名称——vue: ['ref', 'reactive', 'computed', ...]，列表一长就容易遗漏或多余。v0.1.6 带来的通配符'*'
支持，让你一行配置就能导入模块的全部命名导出。同时，generateRouter新增了路由类型声明生成，为@meng-xi/uni-router扩展RouteNameMap
接口，实现类型安全的路由导航。此外，Common 工具模块新增了 5 个通用函数，插件代码也完成了规范化重构。

本版重点：

升级方式：修改devDependencies中版本号为^0.1.6。无 Breaking Changes，完全向后兼容。

一、5 分钟快速上手

1.1 安装与最小配置

{"devDependencies":{"@meng-xi/vite-plugin":"^0.1.6"}}

import{autoImport,generateRouter}from'@meng-xi/vite-plugin'exportdefaultdefineConfig({plugins:[autoImport({imports:{vue:['*']},dts:true,vueTemplate:true}),generateRouter({dts:true})]})

1.2 立刻看到效果

之前：逐一列举要导入的 API

autoImport({imports:{vue:['ref','reactive','computed','watch','watchEffect','onMounted','onUnmounted','nextTick','toRef','toRefs',...]}})

之后：一行搞定

autoImport({imports:{vue:['*']}})

插件会自动从vue的.d.ts类型声明文件中提取所有命名导出，无需手动维护列表。

1.3 路由类型安全

之前：路由名称是普通字符串，拼错不会报错

uni.navigateTo({name:'pagesIndexIndx'})// 拼错了，运行时才发现

之后：启用dts: true后，路由名称有类型检查

uni.navigateTo({name:'pagesIndexIndx'})// TS 报错：类型 '"pagesIndexIndx"' 不能分配给类型 '"pagesIndexIndex" | ...'

二、核心能力一：autoImport 通配符导入

2.1 通配符解析策略

当imports配置中使用'*'时，插件会自动解析模块的所有命名导出：

imports: { vue: ['*'] } ↓ 1. 优先从 .d.ts 类型声明文件解析（最准确） ↓ 失败 2. 尝试作为本地文件路径解析 ↓ 失败 3. 尝试从 node_modules 解析运行时入口 ↓ 失败 4. 返回空数组

为什么优先使用.d.ts？bundler 格式的运行时入口文件（如vue.runtime.esm-bundler.js）通常只包含export { compile }等极少导出，而完整的 API 通过动态方式导出，静态正则无法匹配。.d.ts
文件包含完整的静态类型声明，能准确反映模块的所有导出。

2.2 使用方式

// 简写格式autoImport({imports:{vue:['*'],// 自动导入 vue 的所有命名导出'vue-router':['*'],// 自动导入 vue-router 的所有命名导出pinia:['defineStore','storeToRefs']// 也可以混合使用}})// 完整格式autoImport({imports:[{module:'vue',names:['*']},{module:'lodash',names:['debounce'],defaultImport:false}]})

2.3 Vue SFC 注入

v0.1.6 修复了autoImport与 uni-app 插件的协同问题。此前transform钩子使用enforce: 'post'，导致裸模块标识符无法被 Vite 正确解析。现在改回enforce: 'pre'，并新增injectIntoScriptSetup
函数，将 import 语句注入到<script setup>块内部：

<!-- 处理前 --> <script setup lang="ts"> const count = ref(0) const double = computed(() => count.value * 2) </script> <!-- 处理后 --> <script setup lang="ts"> import { ref, computed } from 'vue' const count = ref(0) const double = computed(() => count.value * 2) </script>

2.4 修复列表

2.5 配置选项变更

三、核心能力二：generateRouter 路由类型声明

3.1 类型声明生成

新增dts选项，为@meng-xi/uni-router模块扩展RouteNameMap接口：

generateRouter({dts:true})

生成的src/router.d.ts：

import'@meng-xi/uni-router'declaremodule'@meng-xi/uni-router'{interfaceRouteNameMap{/** 首页 */pagesIndexIndex:{path:'/pages/index/index';meta:{title:string;isTab:true}}/** 个人中心 */pagesUserProfile:{path:'/pages/user/profile';meta:{title:string;requireAuth:true}}}}

3.2 dts 选项

3.3 类型声明特性

• TSDoc 注释：每条路由自动生成页面标题注释
• 完整元信息映射：meta中的字符串字段类型为string，布尔true字段类型为字面量true
• 增量写入：仅在内容发生变化时才写入文件，减少不必要的文件 IO

四、Common 工具模块增强

v0.1.6 为 Common 工具模块新增了 5 个通用函数：

4.1 common/format

parseTemplate— 替换模板字符串中的{{key}}占位符：

import{parseTemplate}from'@meng-xi/vite-plugin/common/format'parseTemplate('Hello {{name}}!',{name:'World'})// 'Hello World!'parseTemplate('{{YYYY}}-{{MM}}-{{DD}}',getDateFormatParams())// '2026-06-07'

键名中的正则特殊字符会被自动转义，值中的$也会被安全处理。

formatDate— 使用{YYYY}、{MM}等占位符格式化日期字符串：

import{formatDate}from'@meng-xi/vite-plugin/common/format'formatDate(newDate(),'{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}')// '2026-06-07T15:30:00'

4.2 common/fs

writeFileSyncSafely— 同步写入文件，自动创建不存在的目录：

import{writeFileSyncSafely}from'@meng-xi/vite-plugin/common/fs'// 目录不存在时自动递归创建，适用于 transform 等同步钩子writeFileSyncSafely('/project/src/auto-imports.d.ts','declare global { ... }')

shouldUpdateFileContent— 对比文件内容是否需要更新：

import{shouldUpdateFileContent}from'@meng-xi/vite-plugin/common/fs'if(shouldUpdateFileContent('/project/src/router.d.ts',newContent)){writeFileSyncSafely('/project/src/router.d.ts',newContent)}

4.3 common/html

escapeHtmlAttr— 转义 HTML 属性值中的特殊字符：

import{escapeHtmlAttr}from'@meng-xi/vite-plugin/common/html'escapeHtmlAttr('hello "world" & <friends>')// 'hello &quot;world&quot; &amp; &lt;friends&gt;'

转义&、"、'、<、>五种字符，防止属性注入攻击。

五、插件代码规范化重构

按照autoImport/common目录规范，将各插件中不属于插件核心逻辑的函数、常量等提取到common/子目录，通过common/index.ts聚合导出：

重构原则：插件主文件只保留生命周期钩子和核心流程，工具函数和类型定义移入common/，保持代码结构清晰、职责单一。

六、实战场景

6.1 Vue 3 + uni-app 全家桶

import{defineConfig}from'vite'importunifrom'@dcloudio/vite-plugin-uni'import{autoImport,generateRouter}from'./uni_modules/vite-plugin/js_sdk/index.mjs'exportdefaultdefineConfig({plugins:[uni(),autoImport({imports:{vue:['*'],'@dcloudio/uni-app':['onLaunch','onShow','onHide','onLoad']},dts:true,vueTemplate:true}),generateRouter({dts:true})]})

6.2 纯 Vite 项目

import{defineConfig}from'vite'import{autoImport,buildProgress,envGuard}from'@meng-xi/vite-plugin'exportdefaultdefineConfig({plugins:[autoImport({imports:{vue:['*'],'vue-router':['*'],pinia:['defineStore','storeToRefs']},dirs:['src/composables'],dts:'src/auto-imports.d.ts',vueTemplate:true}),buildProgress({format:'bar'}),envGuard({required:{VITE_API_URL:{type:'url',required:true}}})]})

6.3 使用 Common 工具函数构建自定义插件

import{writeFileSyncSafely,shouldUpdateFileContent}from'@meng-xi/vite-plugin/common/fs'import{formatDate}from'@meng-xi/vite-plugin/common/format'import{escapeHtmlAttr}from'@meng-xi/vite-plugin/common/html'// 在 transform 钩子中同步写入类型声明文件functiongenerateAndWriteDts(filePath:string,content:string):void{if(shouldUpdateFileContent(filePath,content)){writeFileSyncSafely(filePath,content)}}// 格式化版本号constversion=formatDate(newDate(),'{YYYY}.{MM}.{DD}')// 安全地注入 HTML 属性constsafeAttr=escapeHtmlAttr(userInput)

七、子路径导出变更

八、迁移指南

从 v0.1.5 升级到 v0.1.6

1. 使用通配符简化配置（可选）

// 之前autoImport({imports:{vue:['ref','reactive','computed','watch','onMounted','onUnmounted','nextTick']}})// 之后autoImport({imports:{vue:['*']}})

2. 启用路由类型声明（可选）

generateRouter({dts:true})// 或自定义路径generateRouter({dts:'src/types/router.d.ts'})

3. 使用新增的 Common 工具函数（可选）

import{parseTemplate,formatDate}from'@meng-xi/vite-plugin/common/format'import{writeFileSyncSafely,shouldUpdateFileContent}from'@meng-xi/vite-plugin/common/fs'import{escapeHtmlAttr}from'@meng-xi/vite-plugin/common/html'

本文基于@meng-xi/vite-plugin@0.1.6版本撰写，所有代码示例均来自实际源码。