# 🚀 开发服务器启动指南

## 🎯 问题诊断

### 错误信息
```
failed to load resource: net::ERR_CONNECTION_REFUSED
```

### 问题原因
**开发服务器没有运行** ❌

浏览器无法连接到 `http://localhost:5173/`，因为没有服务在监听这个端口。

### 类比
```
就像打电话时，对方没有开机
你的浏览器（手机）正常 ✅
但服务器（对方）没开 ❌
```

## ✅ 解决方案

### 方法1: 启动开发服务器（推荐）

#### 步骤1: 打开终端

**VSCode**:
- 快捷键: `` Ctrl + ` ``
- 或菜单: 终端 → 新建终端

**其他编辑器**:
- 打开系统终端
- 进入项目目录

#### 步骤2: 运行启动命令

```bash
npm run dev
```

如果使用 yarn:
```bash
yarn dev
```

如果使用 pnpm:
```bash
pnpm dev
```

#### 步骤3: 等待启动成功

**成功的标志** ✅:

```bash
  VITE v5.4.2  ready in 482 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

  ✓ built in 234ms
```

**关键信息**:
- ✅ `ready in xxx ms` - 服务器已就绪
- ✅ `Local: http://localhost:5173/` - 本地访问地址
- ✅ `built in xxx ms` - 代码编译成功

#### 步骤4: 打开浏览器

访问终端显示的地址：
```
http://localhost:5173/
```

**注意**: 端口号可能不同（5173, 5174, 3000 等），请使用终端显示的端口！

### 方法2: 检查是否已经在运行

#### 步骤1: 检查终端

**查看是否有终端在运行** Vite 服务器

**成功运行的特征**:
```
  ➜  Local:   http://localhost:5173/
  
  (光标在闪烁，等待输入)
```

#### 步骤2: 如果已经运行

- 直接访问显示的地址
- 按 `r + Enter` 重启服务器
- 按 `u + Enter` 显示 URL

## 🔧 常见问题排查

### 问题1: 端口被占用

**错误信息**:
```bash
✘ [ERROR] Failed to start server
  Port 5173 is already in use
```

**原因**: 
- 另一个程序正在使用端口 5173
- 或者之前的服务器没有正确关闭

**解决方案A - 使用其他端口**:

```bash
# Vite 会自动尝试下一个端口
# 继续等待，会看到：
Port 5173 is in use, trying another one...
  ➜  Local:   http://localhost:5174/
```

**解决方案B - 关闭占用的程序**:

Windows:
```bash
# 查找占用端口的进程
netstat -ano | findstr :5173

# 结束进程 (替换 PID 为实际的进程ID)
taskkill /PID <PID> /F
```

Mac/Linux:
```bash
# 查找占用端口的进程
lsof -i :5173

# 结束进程
kill -9 <PID>
```

### 问题2: 依赖未安装

**错误信息**:
```bash
Error: Cannot find module 'react'
  or
Error: Cannot find package 'vite'
```

**解决方案**:

```bash
# 1. 删除旧的依赖
rm -rf node_modules
rm package-lock.json

# 2. 重新安装
npm install

# 3. 启动服务器
npm run dev
```

### 问题3: Node.js 版本过低

**错误信息**:
```bash
Error: The engine "node" is incompatible
Required: >=18.0.0
```

**解决方案**:

1. **检查当前版本**:
```bash
node --version
# 应该看到: v18.x.x 或更高
```

2. **升级 Node.js**:
- 访问 https://nodejs.org/
- 下载并安装 LTS 版本（推荐 v20）
- 重新打开终端

3. **验证安装**:
```bash
node --version
npm --version
```

### 问题4: 编译错误

**错误信息**:
```bash
✘ [ERROR] Could not resolve "xxx"
  or
✘ [ERROR] Transform failed with 1 error
```

**解决方案**:

1. **查看完整错误信息**
   - 阅读终端中的红色错误
   - 找到出错的文件和行号

2. **常见原因**:
   - 导入路径错误
   - 语法错误
   - 类型错误

3. **修复后**:
   - Vite 会自动重新编译
   - 或按 `r + Enter` 手动重启

### 问题5: 浏览器缓存问题

**症状**:
- 服务器正常运行
- 但页面显示旧版本或错误

**解决方案**:

1. **强制刷新**:
   - Windows/Linux: `Ctrl + Shift + R`
   - Mac: `Cmd + Shift + R`

2. **清空缓存**:
   - 按 `F12` 打开开发者工具
   - 右键点击刷新按钮
   - 选择"清空缓存并硬性重新加载"

3. **重启服务器**:
   ```bash
   # 在终端中按 Ctrl + C
   # 然后重新运行
   npm run dev
   ```

## 📋 完整操作流程

### 从零开始

```bash
# 1. 进入项目目录
cd /path/to/your/project

# 2. 安装依赖（首次或更新后）
npm install

# 3. 启动开发服务器
npm run dev

# 4. 等待编译完成
# 看到 "ready in xxx ms"

# 5. 打开浏览器
# 访问 http://localhost:5173/
```

### 日常开发

```bash
# 1. 启动服务器
npm run dev

# 2. 开始编码
# 保存文件后会自动刷新

# 3. 完成后关闭
# 按 Ctrl + C
```

## 💡 开发服务器控制

### 启动后的快捷键

在服务器运行时，可以按以下快捷键：

```bash
h + Enter  - 显示帮助
r + Enter  - 重启服务器
u + Enter  - 显示访问 URL
o + Enter  - 在浏览器中打开
c + Enter  - 清空控制台
q + Enter  - 退出服务器
```

### 停止服务器

**方法1**: 
```bash
Ctrl + C  （推荐）
```

**方法2**:
```bash
q + Enter
```

**方法3**:
- 直接关闭终端窗口

## 🎯 验证服务器运行

### 检查清单

**终端检查** ✅:
- [ ] 看到 "ready in xxx ms"
- [ ] 看到 "Local: http://localhost:xxxx/"
- [ ] 看到 "built in xxx ms"
- [ ] 光标在闪烁（没有错误）

**浏览器检查** ✅:
- [ ] 能访问 http://localhost:5173/
- [ ] 看到登录页面
- [ ] F12 控制台无红色错误

### 成功的样子

**终端**:
```bash
智慧农业生产管理系统 v1.0.0

  VITE v5.4.2  ready in 482 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

  ✓ built in 234ms
  
  (光标闪烁)
```

**浏览器**:
- 显示登录页面
- 可以输入账号密码
- 界面正常显示

## 🚨 紧急救援

### 如果所有方法都不行

#### 方案1: 完全重置

```bash
# 1. 停止所有 Node 进程
# Windows:
taskkill /F /IM node.exe

# Mac/Linux:
pkill -9 node

# 2. 清理项目
rm -rf node_modules
rm -rf .vite
rm package-lock.json

# 3. 重新开始
npm install
npm run dev
```

#### 方案2: 检查防火墙

**Windows 防火墙**:
1. 搜索"Windows Defender 防火墙"
2. 点击"允许应用通过防火墙"
3. 确保 Node.js 已允许

**Mac 防火墙**:
1. 系统偏好设置 → 安全性与隐私
2. 防火墙 → 防火墙选项
3. 确保允许 Node.js

#### 方案3: 使用其他端口

创建 `vite.config.ts`:

```typescript
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    port: 3000,  // 使用端口 3000
    strictPort: false,  // 如果被占用，自动尝试其他端口
  },
});
```

然后重启服务器。

## 📞 需要更多帮助？

### 提供以下信息

1. **操作系统**:
   - Windows 10/11
   - macOS (版本)
   - Linux (发行版)

2. **Node.js 版本**:
   ```bash
   node --version
   npm --version
   ```

3. **终端完整输出**:
   - 从运行 `npm run dev` 开始
   - 到出现错误或成功为止
   - 完整复制粘贴

4. **浏览器信息**:
   - Chrome / Firefox / Safari
   - 版本号

5. **错误截图**:
   - 终端截图
   - 浏览器 F12 控制台截图

## ✅ 快速检查表

### 启动前检查

- [ ] 已进入项目目录
- [ ] 已安装 Node.js (v18+)
- [ ] 已运行 `npm install`
- [ ] 终端没有其他程序在运行

### 启动时检查

- [ ] 运行 `npm run dev`
- [ ] 等待编译完成
- [ ] 看到成功信息
- [ ] 记下端口号

### 访问时检查

- [ ] 使用正确的端口号
- [ ] 地址格式: `http://localhost:5173/`
- [ ] 强制刷新浏览器
- [ ] 检查 F12 控制台

## 🎉 成功标志

**你已经成功启动，如果**:

✅ 终端显示: `ready in xxx ms`  
✅ 终端显示: `built in xxx ms`  
✅ 浏览器能打开 `http://localhost:5173/`  
✅ 看到登录页面  
✅ 可以正常使用系统

## 📚 相关资源

- **Vite 官方文档**: https://vitejs.dev/
- **React 官方文档**: https://react.dev/
- **Node.js 官网**: https://nodejs.org/

---

**最后更新**: 2025-10-16  
**状态**: ✅ 可用  
**优先级**: 🚨 必读
