7.1 KiB

Raw Permalink Blame History

🔥 Air 热加载开发指南

本指南详细介绍如何在 TaskTrack 项目中使用 Air 工具进行 Go 后端热加载开发，大幅提升开发效率。

📋 目录

快速开始
配置详解
使用方法
常见问题
VS Code 集成
性能优化

🚀 快速开始

方法一：使用一键脚本（推荐）

启动热加载开发环境

# Windows
.\dev.bat

# Linux/macOS
./dev.sh

仅启动后端热加载

# Windows
.\hot-reload.bat

# Linux/macOS  
cd backend && air

使用 start.bat 选择模式

.\start.bat
# 选择 "3) 开发模式（热加载）"

方法二：手动操作

进入后端目录
```
cd backend
```
启动 Air
```
air
```

⚙️ 配置详解

.air.toml 配置文件

项目已在 backend/.air.toml 中进行了优化配置：

# Air 热加载配置 - 仅监控后端 Go 代码
root = "."
testdata_dir = "testdata"
tmp_dir = "tmp"

[build]
  args_bin = []
  bin = "./tmp/task-track-backend.exe"
  cmd = "go build -o ./tmp/task-track-backend.exe ."
  delay = 1000
  # 排除不需要监控的目录 - 确保不监控前端和其他非后端目录
  exclude_dir = ["tmp", "vendor", "testdata", "uploads", "database", ".git", "node_modules", "../frontend", "../todo", "../database"]
  exclude_file = []
  exclude_regex = ["_test.go", ".*\\.md$", ".*\\.bat$", ".*\\.sh$", ".*\\.http$"]
  exclude_unchanged = false
  follow_symlink = false
  full_bin = ""
  # 明确指定只监控后端相关目录
  include_dir = [".", "internal", "model", "pkg"]
  # 只监控 Go 代码和配置文件
  include_ext = ["go", "yaml", "yml"]
  include_file = []
  kill_delay = "2s"
  log = "tmp/build-errors.log"
  poll = false
  poll_interval = 0
  post_cmd = []
  pre_cmd = []
  rerun = false
  rerun_delay = 500
  send_interrupt = false
  stop_on_error = true

关键配置说明

include_dir: 明确指定只监控 backend 下的相关目录
exclude_dir: 排除前端、数据库、临时文件等目录
exclude_regex: 排除测试文件、文档、脚本等
include_ext: 只监控 Go 代码和配置文件
delay: 1000ms 防抖，避免频繁重构建

🎯 使用方法

基本使用

启动热加载
```
cd backend
air
```
查看监控状态
- Air 启动时会显示正在监控的目录
- 文件变更时会自动显示构建和重启信息
停止热加载
- 按 Ctrl+C 停止 Air 进程

开发流程

启动服务

# 进入项目根目录
cd e:\apps\python\task_track

# 启动热加载开发
.\dev.bat

开始编码
- 修改 backend/ 下的任意 Go 文件
- 保存文件后 Air 会自动检测变更
- 自动重新编译并重启后端服务
实时查看
- 终端会显示编译状态和服务日志
- 前端可立即访问更新后的 API

监控范围

Air 配置为仅监控以下目录：

backend/ (根目录)
backend/internal/ (业务逻辑)
backend/model/ (数据模型)
backend/pkg/ (工具包)

不会监控：

frontend/ (前端代码)
todo/ (任务文件)
database/ (数据库文件)
tmp/ (临时文件)
测试文件 (*_test.go)
文档文件 (.md)
脚本文件 (.bat, .sh)

🔧 常见问题

Q1: Air 无法启动

# 检查 Air 是否安装
air --version

# 重新安装 Air
go install github.com/air-verse/air@latest

Q2: 端口冲突

# 检查端口占用
netstat -ano | findstr :8080

# 杀死占用进程
taskkill /PID [进程ID] /F

# 或使用项目脚本自动清理
.\dev.bat  # 脚本会自动处理端口冲突

Q3: 前端文件被误监控

配置已优化，确保只监控 backend 目录。如仍有问题：

# 检查 .air.toml 配置
cat backend/.air.toml

# 重新生成配置
cd backend
air init
# 然后用项目提供的配置替换

Q4: 编译错误

# 查看详细错误
cd backend
go build -o ./tmp/task-track-backend.exe .

# 检查 Go 模块
go mod tidy

Q5: 热加载不生效

# 检查文件扩展名
# Air 只监控 .go, .yaml, .yml 文件

# 手动触发重载
# 保存任意 .go 文件即可

# 检查延迟设置
# 当前设为 1000ms，修改后需等待 1 秒

快速重启: 2秒内完成服务器重启
错误停止: 编译错误时停止执行
日志记录: 构建错误日志保存到 tmp/build-errors.log

开发体验优化

自动功能

依赖安装: 自动检查并安装 Air 工具
进程清理: 启动前自动清理已有后端进程
端口检测: 自动检测并清理端口占用
前端集成: 可选同时启动前端开发服务器

开发优势

⚡ 快速重启: 代码保存后 1-2 秒内重启完成
🔍 实时反馈: 编译错误即时显示
🛠️ 无配置: 开箱即用，无需额外配置
🔄 智能监听: 只监听相关文件，避免不必要的重启

Air 命令参考

基本命令

# 启动热加载
air

# 使用指定配置文件
air -c .air.toml

# 显示版本
air --version

# 生成配置文件
air init

配置文件位置

默认配置: backend/.air.toml
构建日志: backend/tmp/build-errors.log
临时文件: backend/tmp/

故障排除

Air 未安装

go install github.com/air-verse/air@latest

端口被占用

# Windows
netstat -ano | findstr :8080
taskkill /f /pid [PID]

# Linux/macOS
lsof -i :8080
kill -9 [PID]

配置文件丢失

cd backend
air init

热加载不工作

检查文件是否在监听目录中
检查文件扩展名是否被包含
查看 tmp/build-errors.log 错误日志
确认没有语法错误

性能优化建议

排除不必要的目录: 在 .air.toml 中排除 uploads、logs 等目录
精确文件类型: 只监听需要的文件扩展名
适当延迟: 设置合理的 delay 避免频繁重启
清理临时文件: 定期清理 tmp/ 目录

与其他工具集成

VS Code 集成

可以在 VS Code 中使用终端运行 air，或者配置 tasks.json:

{
    "label": "启动热加载开发服务器",
    "type": "shell",
    "command": "air",
    "group": "build",
    "options": {
        "cwd": "${workspaceFolder}/backend"
    },
    "isBackground": true
}

Git 忽略

确保 .gitignore 包含以下内容：

backend/tmp/
backend/*.log

最佳实践

代码质量: 保持代码编译通过，避免频繁的编译错误
文件组织: 将配置文件放在合理位置，便于版本控制
环境隔离: 使用不同配置文件区分开发和生产环境
资源清理: 开发结束后及时停止热加载进程

7.1 KiB Raw Permalink Blame History