youwei-business-school/有维项目/youwei-vue/README.md

Youwei Vue - Installation and Deployment Guide

Overview

Youwei Vue is a modern web application built with Vue 3, TypeScript, and Vite. This document provides comprehensive instructions for installing, configuring, and deploying the application.

---

Table of Contents

1. Prerequisites
2. Environment Setup
3. Installation
4. Development
5. Building for Production
6. Deployment
7. Troubleshooting

---

Prerequisites

Before you begin, ensure your system meets the following requirements:

System Requirements

Component	Minimum Version
Node.js	^20.19.0 or >=22.12.0
npm	10.x or higher
Git	2.x or higher

Supported Operating Systems

• Windows 10/11
• macOS 10.15+
• Linux (Ubuntu 20.04+, CentOS 8+, Debian 10+)

Recommended IDE

• VS Code with Vue - Official extension
• Disable Vetur extension if previously installed

---

Environment Setup

1. Install Node.js

Download and install Node.js from the official website:

# Using nvm (recommended)
nvm install 20
nvm use 20

# Or download directly from
# https://nodejs.org/

Verify installation:

node --version  # Should show v20.19.0 or higher
npm --version   # Should show 10.x or higher

2. Install Git

# Windows: Download from https://git-scm.com/download/win
# macOS: brew install git
# Linux: sudo apt-get install git

---

Installation

1. Clone the Repository

git clone <repository-url>
cd youwei-vue

2. Install Dependencies

npm install

This command installs all required dependencies including:

• Vue 3.5.29
• Vue Router 5.0.3
• Pinia 3.0.4
• TypeScript 5.9.3
• Vite 7.3.1
• ESLint & Oxlint for code quality

---

Development

Start Development Server

npm run dev

The development server will start at http://localhost:5173 by default.

Available Scripts

Command	Description
npm run dev	Start development server with hot reload
npm run build	Type-check and build for production
npm run build-only	Build without type checking
npm run type-check	Run TypeScript type checking
npm run preview	Preview production build locally
npm run lint	Run all linters (ESLint + Oxlint)
npm run lint:eslint	Run ESLint with auto-fix
npm run lint:oxlint	Run Oxlint with auto-fix

Development Features

• Hot Module Replacement (HMR): Changes are reflected instantly
• Vue DevTools: Integrated via vite-plugin-vue-devtools
• Path Aliases: Use @/ to reference src/ directory
• TypeScript Support: Full type checking with vue-tsc

---

Building for Production

Production Build

npm run build

This command:

1. Runs TypeScript type checking
2. Compiles and minifies the application
3. Outputs to dist/ directory

Preview Production Build

npm run preview

This serves the production build locally for testing before deployment.

Build Output Structure

dist/
├── assets/
│   ├── index-xxx.js
│   ├── index-xxx.css
│   └── ...
├── favicon.ico
├── index.html
└── logo.png

---

Deployment

Static Hosting

The dist/ folder contains static files that can be deployed to any static hosting service.

Option 1: Nginx

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/youwei-vue/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /assets {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Option 2: Apache

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
</IfModule>

Option 3: Cloud Platforms

• Vercel: Connect Git repository for automatic deployments
• Netlify: Drag and drop dist/ folder or connect Git
• AWS S3 + CloudFront: Upload dist/ contents to S3 bucket
• GitHub Pages: Use GitHub Actions for CI/CD

Docker Deployment

Create a Dockerfile:

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Build and run:

docker build -t youwei-vue .
docker run -p 80:80 youwei-vue

---

Troubleshooting

Common Issues

1. Node Version Mismatch

Error: engines.node incompatible

Solution:

nvm install 20
nvm use 20

2. Port Already in Use

Error: Port 5173 is already in use

Solution:

# Kill process on port 5173
npx kill-port 5173

# Or use a different port
npm run dev -- --port 3000

3. TypeScript Errors

Error: Type checking fails

Solution:

# Run type check separately
npm run type-check

# Check for missing types
npm install --save-dev @types/node

4. Build Failures

Solution:

# Clean and reinstall
rm -rf node_modules package-lock.json
npm install
npm run build

Browser Compatibility

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+

For older browsers, consider adding polyfills to your Vite configuration.

---

Additional Resources

• Vue 3 Documentation
• Vite Documentation
• TypeScript Documentation
• Pinia Documentation

---

Support

For issues and feature requests, please use the project's issue tracker.