项目技术栈详解.md 8.2 KB

Raw Blame History Permalink



项目技术栈详解

最后更新: 2026-02-09
项目名称: map-demo (地图演示项目)
项目类型: Vue 3 + Vite 单页应用


核心技术栈


1. 前端框架与构建工具


技术
版本
用途


Vue
3.2.36
核心框架，使用 Composition API


Vite
2.9.9
构建工具和开发服务器


Vue Router
4.0.15
路由管理（Hash 模式）


Pinia
2.0.14
状态管理


2. UI 组件库


库名
版本
用途


Vant
4.9.6
移动端 UI 组件库（主 UI 库）


Element Plus
2.9.3
PC 端 UI 组件库（辅助）


@element-plus/icons-vue
2.3.1
Element Plus 图标库


font-awesome
4.7.0
图标字体库


3. 地图与全景


技术
版本
用途


@amap/amap-jsapi-loader
1.0.1
高德地图加载器


photo-sphere-viewer
4.8.1
360° 全景查看器（旧版本）


@photo-sphere-viewer/core
5.7.3
全景查看器核心（新版本）


@photo-sphere-viewer/gallery-plugin
5.7.3
全景图库插件


@photo-sphere-viewer/gyroscope-plugin
5.7.3
全景陀螺仪插件


@photo-sphere-viewer/markers-plugin
5.7.3
全景标记插件


@photo-sphere-viewer/stereo-plugin
5.7.3
全景立体插件


@photo-sphere-viewer/virtual-tour-plugin
5.7.3
全景虚拟漫游插件


⚠️ 注意: 项目中同时存在新旧两个版本的全景查看器库，可能存在兼容性问题。


4. 音频与视频


技术
版本
用途


video.js
8.3.0
视频播放器


@videojs-player/vue
1.0.0
Vue 3 视频播放器组件


mui-player
1.6.0
另一个视频播放器


5. 二维码与扫描


技术
版本
用途


@zxing/library
0.21.3
二维码扫描库


6. 工具库


技术
版本
用途


axios
0.27.2
HTTP 请求库


lodash
4.17.21
JavaScript 工具库


dayjs
1.11.3
日期处理库


moment
2.29.3
日期处理库（旧库）


js-cookie
3.0.1
Cookie 管理


qs
6.10.3
查询字符串解析


uuid
8.3.2
UUID 生成


file-saver
2.0.5
文件下载


jszip
3.10.1
ZIP 文件处理


html2canvas
1.4.1
截图功能


jquery
3.6.0
DOM 操作（遗留代码）


7. 样式与动画


技术
版本
用途


less
4.1.2
CSS 预处理器


animate.css
4.1.1
CSS 动画库


8. 微信相关


技术
版本
用途


weixin-js-sdk
1.6.0
微信 JS-SDK


9. 开发工具


技术
版本
用途


@vitejs/plugin-vue
2.3.3
Vite Vue 插件


unplugin-vue-components
0.24.1
组件自动导入


unplugin-auto-import
0.8.8
API 自动导入


unplugin-vue-define-options
0.6.1
支持 setup 语法中定义组件名


vite-plugin-dynamic-import
0.9.6
动态导入增强


@vitejs/plugin-legacy
1.8.2
旧版浏览器支持（已注释）


postcss-px-to-viewport
1.1.1
px 转 vw（已注释）


10. 测试工具


技术
版本
用途


cypress
9.7.0
E2E 测试框架


mocha
10.0.0
单元测试框架


chai
4.3.6
断言库


vconsole
3.14.6
移动端调试工具


11. TypeScript


技术
版本
用途


typescript
4.7.3
TypeScript 支持（主要用于类型检查）


Node.js 版本要求

"engines": {
  "node": "18.13.x"
}


⚠️ 重要: 项目要求使用 Node.js 18.13.x 版本。


Vite 插件配置


1. 组件自动导入

Components({
  resolvers: [VantResolver(), ElementPlusResolver()],
})


自动导入的组件:


Vant 组件（移动端）
Element Plus 组件（PC 端）


效果: 无需手动 import，直接在模板中使用组件


2. API 自动导入

AutoImport({
  dts: 'src/auto-imports.d.ts',
  imports: ['vue', 'vue-router'],
  eslintrc: { enabled: true },
  resolvers: [ElementPlusResolver()],
})


自动导入的 API:


Vue: ref, reactive, computed, watch, onMounted 等
Vue Router: useRouter, useRoute 等


3. Setup 语法支持

DefineOptions()  // 允许在 <script setup> 中定义组件名


4. 动态导入增强

dynamicImport()  // 支持在 import() 中使用路径别名


路径别名配置

{
  '@': 'src',
  '@components': 'src/components',
  '@composables': 'src/composables',
  '@utils': 'src/utils',
  '@images': 'images',
  '@css': 'src/assets/css',
  '@mock': 'src/assets/mock',
  'common': 'src/common',
}


环境变量


开发环境 (.env.development)

VITE_PORT=8006                    # 开发服务器端口
VITE_BASE=/                       # 基础路径
VITE_PROXY_PREFIX=/srv/           # API 代理前缀
VITE_PROXY_TARGET=<后端地址>      # 后端代理目标
VITE_OUTDIR=map                   # 构建输出目录
VITE_APPID=<微信 AppID>           # 微信 AppID
VITE_OPENID=<测试 OpenID>         # 测试用 OpenID


构建配置


输出目录结构

dist (map)
├── index.html
├── static/
│   ├── js/
│   │   ├── [name]-[hash].js
│   │   └── vendor-[hash].js
│   ├── css/
│   │   └── [name]-[hash].css
│   └── [ext]/
│       └── [name]-[hash].[ext]


代码分割策略

manualChunks (id) {
  if (id.includes('node_modules')) {
    // 每个 node_modules 包单独打包
    return id.toString().split('node_modules/')[1].split('/')[0].toString();
  }
}


部署脚本

项目包含 4 个自动化部署脚本：


命令
目标服务器
说明


npm run dev_upload
ipadbiz-inner:/opt/space-dev/f
开发环境


npm run oa_upload
ipadbiz-inner:/opt/oa/f
OA 环境


npm run walk_upload
ipadbiz-inner:/opt/walk/f
Walk 环境


npm run xys_upload
zhsy@oa.jcedu.org:/home/www/f:12101
XYS 环境（SSH 端口 12101）


每个脚本执行：


构建项目 (npm run build)
打包 (npm run tar)
SCP 传输 (npm run scp-*)
远程解压 (npm run dec-*)
清理本地文件 (npm run remove_tar, npm run remove_dist)


已知问题与注意事项


1. 版本冲突


⚠️ photo-sphere-viewer: 同时使用 4.8.1 和 5.7.3 两个版本
⚠️ 日期库: 同时使用 dayjs 和 moment
⚠️ 视频播放器: 同时使用 video.js 和 mui-player


2. 已注释的功能


🚫 旧版浏览器支持: @vitejs/plugin-legacy 已注释
🚫 px 转 vw: postcss-px-to-viewport 已注释
🚫 多页面应用: mono1, mono2 入口已注释


3. jQuery 依赖

项目仍使用 jQuery (3.6.0)，建议：


新代码避免使用 jQuery
逐步迁移到 Vue 原生 API 或 VueUse


4. 全局样式注入

Less 配置中全局注入 base.less:

additionalData: `@import "${path.resolve(__dirname, 'src/assets/styles/base.less')}";`


影响: 所有 .vue 文件中的 <style lang="less"> 都会自动包含全局样式。


技术债务


高优先级


全景查看器版本统一: 统一使用 5.x 版本，移除 4.x

日期库统一: 统一使用 dayjs，移除 moment

jQuery 移除: 逐步移除 jQuery 依赖


中优先级


视频播放器统一: 选择一个播放器，移除另一个

TypeScript 类型完善: 添加完整的类型定义

测试覆盖: 补充单元测试和 E2E 测试


低优先级


代码格式化: 添加 ESLint + Prettier

Git Hooks: 添加 Husky + lint-staged

文档完善: API 文档、组件文档


参考资源


Vue 3 文档
Vite 文档
Vant 文档
Element Plus 文档
高德地图文档
Photo Sphere Viewer 文档