第10章构建配置与部署

10.1 Vite 配置

vite.config.ts 是项目的构建配置核心：

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),  // 别名
    },
  },
  build: {
    chunkSizeWarningLimit: 1000,
    rollupOptions: {
      output: {
        manualChunks: {
          'psv-core': ['@photo-sphere-viewer/core'],
          'psv-plugins': [
            '@photo-sphere-viewer/markers-plugin',
            '@photo-sphere-viewer/plan-plugin',
          ],
          'leaflet': ['leaflet'],
        },
      },
    },
  },
})

10.1.1 路径别名

'@': fileURLToPath(new URL('./src', import.meta.url))

将 @ 映射到 ./src，方便导入。

10.1.2 构建分包

manualChunks: {
  'psv-core': ['@photo-sphere-viewer/core'],
  'psv-plugins': ['@photo-sphere-viewer/markers-plugin', '@photo-sphere-viewer/plan-plugin'],
  'leaflet': ['leaflet'],
}

将大体积依赖拆分为独立 chunk：

psv-core：PSV 核心
psv-plugins：PSV 插件
leaflet：地图库

这解释了 dist/ 里的 psv-core-*.js、psv-plugins-*.js、leaflet-*.js 文件。

10.2 TypeScript 配置

项目采用 project references 结构，包含三个配置文件：

10.2.1 tsconfig.json（根配置）

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

空 files + references 指向 app 和 node 两个子配置。

10.2.2 tsconfig.app.json（应用代码）

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "jsx": "preserve",
    "noEmit": true,
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"]
}

target ES2022：目标 ES 版本
module ESNext：ES 模块
moduleResolution bundler：bundler 解析模式
strict：严格模式
paths：路径别名映射

10.2.3 tsconfig.node.json（Node 环境）

{
  "compilerOptions": {
    "types": ["node"],
    "composite": true
  },
  "include": ["vite.config.ts"]
}

仅包含 vite.config.ts，types: ["node"] 提供 Node 类型。

10.3 入口文件

10.3.1 main.ts

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import './styles/psv.css'  // 全局样式

createApp(App).mount('#app')

10.3.2 index.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link rel="icon" type="image/svg+xml" href="/icons/link-pin.svg" />
  <title>360全景地图联动演示</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; overflow: hidden; }
  </style>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>

lang="zh-CN"：中文语言
favicon 使用本地 link-pin.svg
overflow: hidden：隐藏滚动条（全屏应用）

10.4 构建流程

10.4.1 开发构建

npm run dev

启动 Vite 开发服务器，支持热更新。

10.4.2 生产构建

npm run build

执行流程：

vue-tsc -b：类型检查
vite build：生产构建

10.4.3 类型检查

npm run typecheck

仅运行类型检查（含 vite.config.ts）。

10.4.4 预览

npm run preview

预览生产构建产物。

10.5 部署

10.5.1 构建产物

生产构建输出到 dist/ 目录，包含：

dist/
├── index.html
├── assets/
│   ├── index-*.js
│   ├── psv-core-*.js
│   ├── psv-plugins-*.js
│   ├── leaflet-*.js
│   └── index-*.css
└── icons/
    └── link-pin.svg

10.5.2 部署方式

由于是纯前端项目，可以部署到任何静态服务器：

GitHub Pages：推送到 GitHub 仓库，启用 Pages
Netlify / Vercel：连接仓库自动部署
Nginx：将 dist/ 目录作为站点根目录

10.5.3 部署注意事项

网络依赖：全景图片与地图瓦片来自公共资源（PSV 官方 CDN / OpenStreetMap），需要联网访问
base 路径：如果部署到子路径，需要在 vite.config.ts 中配置 base

10.6 构建优化总结

优化项	实现方式
路径别名	`@` → `./src`
代码分包	manualChunks 拆分大依赖
类型检查	vue-tsc 严格模式
构建警告	chunkSizeWarningLimit 1000

10.7 下一步

理解了构建与部署后，进入第11章二次开发指南了解如何扩展项目。

第10章 构建配置与部署