D1 学习笔记:从 0 搭建 AI 项目环境,300MB 视频差点毁了我的仓库

系列:海口三港 AI 全栈实战 · 从参赛大屏到 AI 平台
仓库:https://github.com/2003Tim/haikou-ai-port

前言:为什么重新开始

我是计算机研一学生,方向是人工智能,目标是 2027 届秋招拿到 AI 应用工程师 offer。

手上有一个本科时期的参赛项目——「海口三港综合枢纽可视化智慧平台」(纯前端大屏,5 个 HTML 页面 + ECharts + 百度地图)。所有数据都是硬编码,没有后端、没有数据库、没有 AI。

我决定用 12 个月时间把这个项目改造成集成 LLM/RAG/Agent 的 AI 智慧管控平台,既是真实的全栈学习过程,也是求职作品集。

这是 Day 1 的记录:搭建环境、初始化 GitHub、第一次 commit。

听起来简单对吧?但我踩了 3 个坑,其中 1 个差点把仓库撑到 300MB——直到 GitHub 给我发警告我才反应过来。

一、4 个工具一次装齐

我需要的环境:

  • Git — 版本管理
  • Python 3.11+ — 后端语言(我装的是 3.12.10)
  • uv — Python 包管理器,比 pip 快 10 倍
  • VS Code — 编辑器

为了检测环境是否齐全,我写了个 PowerShell 脚本 scripts/check-env.ps1,核心思路是用 Get-Command 检查命令是否存在:

function Test-Tool {
    param([string]$Name, [string]$ExePath)
    $cmd = Get-Command $ExePath -ErrorAction SilentlyContinue
    if ($cmd) {
        $version = & $ExePath --version 2>&1 | Select-Object -First 1
        Write-Host "[OK] $Name : $version" -ForegroundColor Green
    } else {
        Write-Host "[X]  $Name : 未安装" -ForegroundColor Red
    }
}

💡 为什么不用 try/catch?PowerShell 5.1 对函数体内的 try/catch 解析有 bug,会误判"缺少右括号"。Get-Command -ErrorAction SilentlyContinue 是更稳健的写法。

跑出来:

[OK] Git : git version 2.45.1.windows.1
[OK] Python : Python 3.12.10
[OK] uv : uv 0.12.1
[OK] VS Code : 1.133.0

一次通过。

二、GitHub 建仓 + 第一次 commit

GitHub 上新建仓库 haikou-ai-port(Public),然后本地初始化:

cd F:\storeFiles\Code\Haikou
git init
git branch -M main
git config --global user.name "2003Tim"
git config --global user.email "1301474407@qq.com"

git add .
git commit -m "chore: 初始化项目,加入开发计划和检测脚本"

提交结果:68 files changed, 89118 insertions(+)。

那一刻有点爽——本科参赛的代码正式进入版本管理了。

三、300MB 视频差点毁了我的仓库

推送到 GitHub 时,控制台打出一行警告:

warning: File video/monitor2.mp4 is 57.43 MB; this is larger than
GitHub's recommended maximum file size of 50.00 MB
...
Total 77 (delta 10), reused 0 (delta 0), pack-reused 0 (from 0)
... 306.55 MiB | 7.07 MiB/s ...

我把项目里 8 个监控视频(每个 30-60MB)全部 push 上去,仓库体积 306MB。

后果我后来才意识到:

  1. 面试官 clone 要等 10 分钟 —— 大概率直接关掉
  2. 仓库看起来"很乱" —— 不像作品集,像 U 盘备份
  3. GitHub 推荐单文件 50MB 上限 —— 再大直接拒收

💡 .gitignore 应该从 Day 1 就写好,而不是"出问题了再补"。

四、修复:从 git 移除 + 完善 .gitignore

关键命令是 git rm --cached,只从 git 追踪 中移除,本地文件保留:

# --cached 关键:只从 git 移除,本地视频文件还在
git rm -r --cached video/

更新 .gitignore,把视频和大文件类型全部排除:

# 监控视频不入仓库(改用 Git LFS 或外部存储)
video/
*.mp4
*.mov
*.avi

# Python 通用
__pycache__/
*.py[cod]
.venv/
.env

# Node / 前端(后续 Vue 阶段)
node_modules/
dist/

# IDE / 系统
.vscode/
.DS_Store
Thumbs.db

再次 push:

4 files changed, 2.74 KiB | 2.74 MiB/s

仓库从 306MB 降到几 KB。✅

五、我学到的 3 件事

  1. .gitignore 从 Day 1 就该配好 —— 提前规划哪些文件不该入 git,比事后清理省 100 倍精力
  2. 大文件不要进 git —— 视频、数据集、模型权重(以后 PyTorch 模型)、字体大文件 —— 用 Git LFS 或外部存储(OSS/COS)
  3. git rm --cached 是清理误提交文件的正确姿势 —— 不删本地文件,只解除追踪

六、Day 1 完整命令清单(可直接复用)

# 1. 全局配置(只做一次)
git config --global user.name "你的名字"
git config --global user.email "你的GitHub邮箱"

# 2. 本地初始化
cd <你的项目目录>
git init
git branch -M main

# 3. 先写 .gitignore(重要!先写好再 add)
# ... 在 .gitignore 里写好要排除的规则 ...

# 4. 第一次提交
git add .
git commit -m "chore: 初始化项目"

# 5. GitHub 上创建仓库后,连接远程
git remote add origin https://github.com/<用户名>/<仓库名>.git
git push -u origin main

下一步:Day 2 写什么?

Day 2 我会写 README 初稿——这是项目门面,面试官点开 GitHub 第一眼就决定看不看你的代码。一份"30 秒讲清楚在做什么"的 README,比 1000 行代码更重要。

参考资料

posted @ 2026-08-21 17:14  吴逸清  阅读(3)  评论(0)    收藏  举报