zyuas.com/zyuas-neo

ZYUAS Neo - 企业官网重构项目

使用 Vue 3 + TypeScript + Element Plus + Vite + SCSS 构建的企业官方网站

版本： v1.1.0
构建状态： ✅ 成功
类型检查： ✅ 通过
最后更新： 2026-02-26

---

📋 目录

1. 项目简介
2. 技术栈
3. 快速开始
4. 项目结构
5. 已完成功能
6. TypeScript 类型系统
7. 设计系统
8. SCSS 样式系统
9. 响应式布局
10. 图标使用指南
11. 开发规范
12. 构建与部署
13. 常见问题

---

📦 项目简介

使用 Vue 3 + TypeScript + Element Plus + Vite + SCSS 构建的企业官方网站，替代原有的 Vue 2 + Bootstrap 版本。

技术升级对比

组件	原版本	新版本	改进
框架	Vue 2.7.16	Vue 3.5.25	Composition API + TypeScript
构建工具	Webpack 4	Vite 7	10x 更快构建
UI 框架	Bootstrap 3	Element Plus 2.13	现代化组件库
路由	Vue Router 3	Vue Router 4	完整 TS 支持
状态管理	Vuex 3	Pinia 3	更简洁的 API
轮播	Swiper 4	Swiper 12	最新特性
样式	CSS	SCSS	变量 + 混入系统
类型系统	-	TypeScript 5.9	编译时类型检查

---

🛠️ 技术栈

技术	版本	说明
Vue	3.5.25	Composition API + <script setup lang="ts">
TypeScript	5.9.3	完整类型系统支持
Element Plus	2.13.2	UI 组件库
Vite	7.3.1	下一代构建工具
Vue Router	4.6.4	路由管理
Pinia	3.0.4	状态管理
Swiper	12.1.2	轮播组件
SCSS	latest	CSS 预处理器
Animate.css	latest	动画库

---

🚀 快速开始

# 进入项目目录
cd zyuas-neo

# 安装依赖
npm install

# 开发模式
npm run dev
# 访问 http://localhost:5173

# 类型检查
npm run type-check

# 生产构建（含类型检查）
npm run build

# 跳过类型检查构建
npm run build:skip-typecheck

# 预览构建结果
npm run preview

构建状态

✅ 构建成功 - 生产构建已通过 (npm run build)
✅ 类型检查通过 - TypeScript 编译无错误 (npm run type-check)

✓ 1563 modules transformed.
✓ built in 4.12s

dist/
├── index.html
└── static/
    ├── *.css
    ├── *.js
    └── assets/

---

📁 项目结构

zyuas-neo/
├── src/
│   ├── assets/
│   │   ├── styles/
│   │   │   ├── variables.scss    # SCSS 变量
│   │   │   ├── mixins.scss       # SCSS 混入
│   │   │   ├── components.scss   # 可复用组件
│   │   │   └── global.scss       # 全局样式
│   │   └── images/               # 图片资源 (65+ 文件)
│   ├── types/
│   │   ├── vite-env.d.ts         # Vite 环境类型
│   │   ├── nav.ts                # 导航类型定义
│   │   └── home.ts               # 首页类型定义
│   ├── components/
│   │   ├── Header.vue.ts         # 头部导航 (TypeScript)
│   │   ├── Footer.vue.ts         # 页脚 (TypeScript)
│   │   └── GoTop.vue.ts          # 回到顶部 (TypeScript)
│   ├── config/
│   │   └── nav-config.ts         # 导航配置 (TypeScript)
│   ├── router/
│   │   └── index.ts              # 路由配置 (TypeScript)
│   ├── views/
│   │   ├── HomePage.vue.ts       # 首页 (TypeScript)
│   │   ├── Products/             # 产品页面 (5 个，TypeScript)
│   │   ├── Solutions/            # 解决方案页面 (5 个，TypeScript)
│   │   ├── AIDevelopment/        # AI 开发页面 (3 个，TypeScript)
│   │   ├── News/                 # 新闻页面 (TypeScript)
│   │   ├── Info/                 # 公司信息 (TypeScript)
│   │   └── ContactUs/            # 联系我们 (TypeScript)
│   ├── App.vue.ts                # 根组件 (TypeScript)
│   └── main.ts                   # 入口文件 (TypeScript)
├── index.html
├── package.json
├── tsconfig.json                 # TypeScript 配置
├── tsconfig.node.json            # Node 环境配置
├── vite.config.ts                # Vite 配置
└── README.md

---

✅ 已完成功能

核心页面 (22 个)

类别	页面	文件数	状态
首页	HomePage	1	✅
产品与服务	Products	5	✅
解决方案	Solutions	5	✅
AI 开发	AIDevelopment	3	✅
其他	News/Info/ContactUs	3	✅
公共组件	Header/Footer/GoTop	3	✅

技术特性

• TypeScript 完整类型支持
• SCSS 样式系统（变量 + 混入 + 可复用组件）
• 响应式布局（移动端/平板/桌面）
• Element Plus 组件集成
• Swiper 12 轮播
• 路由懒加载
• 页面过渡动画
• 全局图标注册
• 编译时类型检查

---

🔷 TypeScript 类型系统

类型配置文件

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "jsx": "preserve",
    "moduleResolution": "bundler",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

类型定义文件

src/types/nav.ts - 导航类型

export interface NavItem {
  name: string
  path: string
  children: NavChildItem[]
}

export interface NavChildItem {
  name: string
  path: string
}

export interface NavAction {
  name: string
  path: string
  type: 'primary' | 'secondary'
}

src/types/home.ts - 首页类型

export interface SwiperSlide {
  img: string
  title: string
  content: string
}

export interface SolutionItem {
  path: string
  title: string
  description: string
  image: string
}

在组件中使用类型

<script setup lang="ts">
import { ref } from 'vue'
import type { SolutionItem } from '@/types/home'

const solutionsList = ref<SolutionItem[]>([
  {
    path: '/solutions/surveying',
    title: '基础测绘',
    description: '快速进行大范围二维、三维建模',
    image: '...'
  }
])
</script>

可用命令

命令	说明
npm run type-check	仅类型检查
npm run build	生产构建（含类型检查）
npm run build:skip-typecheck	跳过类型检查构建

---

🎨 设计系统

主题色

$primary-color: #1e73be;      // 主色（蓝色）
$primary-light: #3b82f6;      // 亮蓝
$primary-dark: #185a9d;       // 深蓝
$primary-gradient: linear-gradient(135deg, #1e73be, #3b82f6);

中性色

$text-primary: #1a1a1a;       // 主文本
$text-regular: #555555;       // 常规文本
$text-tertiary: #666666;      // 次要文本
$text-muted: #999999;         // 弱化文本

间距系统

$spacer-1: 10px;
$spacer-2: 20px;
$spacer-3: 30px;
$spacer-4: 40px;
$spacer-5: 50px;
$spacer-6: 60px;

圆角与阴影

// 圆角
$radius-sm: 8px;
$radius-md: 12px;
$radius-lg: 16px;
$radius-xl: 20px;

// 阴影
$shadow-sm: 0 2px 8px rgba(0, 0, 0, 0.08);
$shadow-md: 0 8px 32px rgba(0, 0, 0, 0.12);
$shadow-lg: 0 20px 60px rgba(0, 0, 0, 0.15);

---

📐 SCSS 样式系统

变量文件 (variables.scss)

// 主题色
$primary-color: #1e73be;
$primary-light: #3b82f6;

// 中性色
$text-primary: #1a1a1a;
$text-regular: #555555;

// 间距
$spacer-1: 10px;
$spacer-2: 20px;

// 断点
$breakpoint-sm: 576px;
$breakpoint-md: 768px;
$breakpoint-lg: 992px;
$breakpoint-xl: 1200px;

混入文件 (mixins.scss)

// 响应式
@mixin mobile { @media (max-width: 767px) { @content; } }
@mixin tablet { @media (min-width: 768px) and (max-width: 991px) { @content; } }
@mixin desktop { @media (min-width: 992px) { @content; } }

// Flexbox
@mixin flex-center { display: flex; align-items: center; justify-content: center; }
@mixin flex-between { display: flex; align-items: center; justify-content: space-between; }

// 玻璃拟态
@mixin glass-morphism {
  background: rgba(255, 255, 255, 0.8);
  border: 1px solid rgba(255, 255, 255, 0.5);
  backdrop-filter: blur(10px);
}

在 Vue 文件中使用

<template>
  <div class="page">
    <div class="page-banner">
      <h1>标题</h1>
    </div>
  </div>
</template>

<script setup lang="ts">
// TypeScript 代码
</script>

<style lang="scss">
@import '@/assets/styles/variables';
@import '@/assets/styles/mixins';

.page {
  padding: $spacer-3;

  @include mobile {
    padding: $spacer-2;
  }
}
</style>

---

📱 响应式布局

容器边距系统

断点	屏幕宽度	容器边距	说明
桌面端	> 1200px	20px	标准边距
平板端	768px - 1200px	30px	增加边距
移动端	< 768px	20px	标准边距

响应式字体

元素	桌面端	平板端	移动端
根字体	16px	16px	14px
章节标题	36px	28px	24px
大标题	42px	32px	28px

断点混入

// 移动端 (< 768px)
@include mobile {
  .element {
    // 移动端样式
  }
}

// 平板端 (768px - 991px)
@include tablet {
  .element {
    // 平板端样式
  }
}

// 桌面端 (>= 992px)
@include desktop {
  .element {
    // 桌面端样式
  }
}

---

🔣 图标使用指南

已用图标清单

导航组件

图标	用途
ArrowDown, ArrowRight	下拉菜单、按钮
Menu, Close	移动端导航
ArrowUp	回到顶部

首页

图标	用途
ArrowLeft, ArrowRight	轮播图导航
Connection	解决方案链接
Star, Monitor, Picture, DataAnalysis	技术优势
Service, Timer, Medal	服务优势

图标使用方式

<script setup lang="ts">
import { ArrowRight, Star } from '@element-plus/icons-vue'
</script>

<template>
  <el-icon><ArrowRight /></el-icon>
</template>

类型声明

所有 Element Plus 图标已在 src/types/vite-env.d.ts 中声明：

declare module '@element-plus/icons-vue' {
  export const ArrowDown: any
  export const ArrowRight: any
  export const CircleCheckFilled: any
  // ... 更多图标
}

---

📝 开发规范

组件命名

• 使用 PascalCase（大驼峰）
• 页面组件首字母大写
• 公共组件首字母大写

TypeScript 代码风格

• 使用 <script setup lang="ts"> 语法
• 为所有 ref/reactive 添加类型注解
• 为函数参数和返回值添加类型注解

• 使用 interface 定义对象类型

  // ✅ 推荐
  interface User {
  name: string
  age: number
  }
  
  const user = ref<User>({
  name: 'John',
  age: 30
  })
  
  const greet = (name: string): string => {
  return `Hello, ${name}`
  }
  

样式规范

<style lang="scss">
// 1. 先导入变量和混入
@import '@/assets/styles/variables';
@import '@/assets/styles/mixins';

// 2. 使用 SCSS 变量
.my-component {
  color: $text-primary;
  padding: $spacer-3;

  // 3. 使用混入
  @include mobile {
    padding: $spacer-2;
  }
}
</style>

文件组织

src/
├── types/              # TypeScript 类型定义
├── assets/
│   ├── styles/         # 全局样式
│   └── images/         # 图片资源
├── components/         # 公共组件
├── views/             # 页面组件
├── router/            # 路由配置
└── config/            # 配置文件

---

🏗️ 构建与部署

开发环境

npm run dev
# 访问 http://localhost:5173

生产构建

# 含类型检查（推荐）
npm run build

# 跳过类型检查
npm run build:skip-typecheck

构建输出

✓ 1563 modules transformed.
✓ built in 4.12s

dist/
├── index.html              0.96 kB
└── static/
    ├── element-plus-*.js   # Element Plus (1MB+)
    ├── vue-vendor-*.js     # Vue 相关 (100KB+)
    ├── swiper-*.js         # Swiper (69KB)
    └── *.css, *.js         # 其他资源

推荐部署平台

• Vercel
• Netlify
• GitHub Pages
• 阿里云 OSS
• 腾讯云 COS
• Nginx 服务器

---

❓ 常见问题

TypeScript 类型错误

问题： 编译时报 Property 'xxx' does not exist on type 错误

解决： 为对象添加正确的类型注解或使用 interface 定义

// ❌ 错误
const data = ref({})
data.value.name = 'test'

// ✅ 正确
interface Data {
  name: string
}
const data = ref<Data>({ name: '' })

图标类型未找到

问题： Module has no exported member 'Xxx'

解决： 在 src/types/vite-env.d.ts 中添加图标声明

declare module '@element-plus/icons-vue' {
  export const Xxx: any
}

构建产物过大

问题： 构建后文件过大

解决：

1. 使用路由懒加载（已实现）
2. 压缩图片资源
3. 使用 CDN 加载 Element Plus

---

📊 项目统计

类型	数量
Vue 组件 (TypeScript)	22
TypeScript 配置文件	3
类型定义文件	4
SCSS 文件	4
图片资源	65+
路由	17
总代码行数	~5500+
构建时间	~4.1s

---

🌐 浏览器支持

• Chrome >= 90
• Firefox >= 88
• Safari >= 14
• Edge >= 90

---

📄 许可证

MIT

---

上海展域航空技术有限公司 © 2025