小组长上传教程
本教程详细介绍如何将你们小组的项目成果提交到岭创之夏项目展示平台。
前置准备
在开始之前，请确保你已经：
- 注册 GitHub 账号 — https://github.com/signup
- 安装 Git — Git 下载地址
- 安装 Node.js 和 npm — 用于在提交前验证 VitePress 网站能够正常构建
- 准备项目资料 — 整理好代码、文档、截图等材料
提交流程概览
准备项目资料 → 克隆仓库 → 创建分支 → 添加项目文件 → 创建展示页面 → 更新侧边栏配置 → 本地构建验证 → 提交 PR → 审核合并 → 网站自动更新第一步：克隆主仓库
- 访问主仓库：https://github.com/binbatlab/26-lingchuang-summer
- 确保你已被添加为仓库协作者（联系管理员开通权限）
# 克隆主仓库到本地
git clone git@github.com:binbatlab/26-lingchuang-summer.git
cd 26-lingchuang-summer第二步：创建项目分支
# 创建并切换到你的项目分支
# 分支命名格式：project/你的小组名
git checkout -b project/你的小组名⚠️ 分支命名规范：使用英文小写 + 连字符，例如
project/smart-agriculture、project/ai-trading
第三步：添加项目文件
你需要分别在两个位置添加文件：
- 源代码 →
sources/你的小组名/（代码和研发文档） - 展示图片 →
docs/assets/你的小组名/（网站展示用的截图） - 展示页面 →
docs/projects/你的小组名.md（项目介绍页面）
目录结构
26-lingchuang-summer/
├── sources/ # 源代码仓库
│ └── 你的小组名/ # 例如 smart-agriculture
│ ├── README.md # 项目说明文件（必需）
│ ├── src/ # 源代码目录
│ │ ├── backend/ # 后端代码
│ │ └── frontend/ # 前端代码
│ ├── docs/ # 项目文档
│ │ ├── requirements.md # 需求分析
│ │ ├── design.md # 系统设计
│ │ └── api.md # API 文档
│ └── .gitignore # Git 忽略文件配置
│
└── docs/ # 网站源文件
├── assets/ # 展示图片（给网站用）
│ └── 你的小组名/ # 你组的截图文件夹
│ ├── logo.png # 项目 Logo（≥ 128×128px）
│ ├── screenshot-dashboard.png # Web 端主界面截图
│ ├── screenshot-mobile.png # 移动端界面截图（如有）
│ ├── photo-hardware.jpg # 硬件实物照片（如有）
│ ├── architecture.png # 系统架构图
│ └── demo.mp4 # 项目演示视频（可选）
│
└── projects/ # 项目展示页面
└── 你的小组名.md # 项目介绍（必需）⚠️ 重要区分：
sources/存放项目源代码，docs/assets/存放网站展示用的截图。网站只能引用docs/下的文件，不要用 GitHub 绝对路径。
必需内容清单
| 位置 | 文件 | 是否必需 | 说明 |
|---|---|---|---|
sources/你的小组名/README.md | 项目说明 | ✅ 必需 | 项目简介、技术栈、运行方法 |
sources/你的小组名/src/ | 源代码 | ✅ 必需 | 项目源代码 |
docs/assets/你的小组名/logo.png | Logo | ✅ 必需 | 正方形，≥ 128×128px |
docs/assets/你的小组名/screenshot-dashboard.png | 主界面截图 | ✅ 必需 | Web 端核心功能界面 |
docs/assets/你的小组名/architecture.png | 架构图 | 推荐 | 系统架构图 |
docs/projects/你的小组名.md | 展示页面 | ✅ 必需 | 项目介绍 Markdown |
📸 截图规范
项目截图是展示成果的核心内容，请严格按照以下规范准备。
| 规范项 | 要求 |
|---|---|
| 文件格式 | PNG（截图/图表）或 JPG（照片） |
| 最大宽度 | 1200px |
| 文件大小 | ≤ 500KB（截图），≤ 2MB（照片），≤ 20MB（视频） |
| 命名规则 | 英文小写 + 连字符，如 screenshot-dashboard.png |
| Logo 尺寸 | 正方形构图，≥ 128×128px |
截图内容要求：
- ✅ 展示核心功能页面，包含真实数据（非空白/占位状态）
- ✅ 如有硬件，提供清晰的光线充足的实物照片
- ✅ 架构图使用 draw.io、Excalidraw 等工具绘制，导出为 PNG
- ❌ 不要提交模糊、过暗、带有无关内容的截图
- ❌ 不要使用手机对着屏幕拍照（使用系统截图工具）
推荐工具：
| 用途 | 工具 |
|---|---|
| 界面截图 | macOS: Cmd+Shift+4 / Windows: Win+Shift+S |
| 架构图 | draw.io / Excalidraw |
| 图片压缩 | TinyPNG / Squoosh |
| GIF 动图 | LICEcap(macOS) / ScreenToGif(Win) |
📖 项目展示效果可参考 样例项目：智能农业监测系统
注意
请勿提交以下内容：
node_modules/目录（及类似依赖目录）- 编译产物（
.exe、.class等） - 包含敏感信息的配置文件（密码、密钥等）
- 大文件（单个文件超过 10MB）
第四步：编写项目展示页
除了在 sources/ 目录下提交代码外，你还需要在 docs/projects/ 目录下创建项目展示页面。
创建展示页面
在 docs/projects/ 目录下创建一个以小组名命名的 Markdown 文件：
# 例如
touch docs/projects/你的小组名.md展示页面模板
请参考 样例项目页面，模板结构如下：
# 项目名称
xxx
## 基本信息
| 项目 | 详情 |
|------|------|
| **项目名称** | xxx |
| **小组名称** | xxx |
| **项目方向** | xxx |
| **项目周期** | 2026年7月 — 2026年8月 |
## 小组成员
| 姓名 | 角色 | GitHub |
|------|------|--------|
| xxx | 组长 | [@xxx](https://github.com/xxx) |
## 项目简介
一段话说明项目的背景、目标和解决的问题。
## 技术栈
### 前端/后端/硬件
- **语言**: xxx
- **框架**: xxx
- **数据库**: xxx
## 核心功能
1. **功能A** — 功能描述
2. **功能B** — 功能描述
## 项目 Logo
<img src="../assets/example/logo.svg" alt="项目 Logo" width="160" />
---
## 项目截图
### Web 端主界面
---
## 系统架构图
## 代码仓库
- 项目源码: [GitHub链接]()
## 演示
在线演示地址: [演示链接]()
## 项目亮点
- 亮点1
- 亮点2
## 项目总结
总结实践过程中的收获和体会。第五步：更新项目列表
编辑 docs/projects/index.md，在"各组项目"表格中添加你们组的条目：
| 项目名称 | 小组名 | 方向 | 链接 |
|----------|--------|------|------|
| 你们的项目名 | 你们的小组名 | 项目方向 | [查看详情](/projects/你的小组名) |第六步：更新侧边栏配置
为了让你们的项目出现在网站侧边栏中，需要编辑 docs/.vitepress/config.mts。
找到 sidebar 配置中的 '/projects/' 部分，在 items 数组末尾添加你们的项目条目：
'/projects/': [
{
text: '作品展示',
items: [
{ text: '项目总览', link: '/projects/' },
{ text: '样例项目：智能农业监测系统', link: '/projects/sample' },
{ text: 'LoRa星型组网', link: '/projects/LoRa' },
// ... 其他已有项目 ...
{ text: '你们的项目名', link: '/projects/你的小组名' }, // ← 新增这一行
]
}
],⚠️ 注意：
link路径中的你的小组名应与docs/projects/你的小组名.md的文件名保持一致。
第七步：本地构建验证
在提交任何 VitePress 相关代码之前，必须先在主仓库根目录验证网站能够正常构建。首次克隆仓库或依赖有变化时，先安装依赖：
# 在 26-lingchuang-summer 仓库根目录执行
npm ci
# 构建 VitePress 网站
npm run build看到 build complete 表示构建成功。如果命令出现报错，请先根据错误信息修复，再重新运行 npm run build；构建失败时不要提交或推送代码。
⚠️ 提交前必查：只要修改了
docs/、docs/.vitepress/、package.json或package-lock.json，都必须重新运行npm run build并确认成功。
第八步：提交 Pull Request
# 1. 添加所有新文件
git add sources/你的小组名/
git add docs/assets/你的小组名/
git add docs/projects/你的小组名.md
git add docs/projects/index.md
git add docs/.vitepress/config.mts
# 2. 提交
git commit -m "docs: 添加 xxx 小组项目展示
- 提交项目源代码
- 添加项目截图和展示资源
- 添加项目展示页面
- 更新项目列表
- 更新侧边栏配置"
# 3. 推送到主仓库
git push origin project/你的小组名推送后，在 GitHub 上：
- 进入主仓库页面：https://github.com/binbatlab/26-lingchuang-summer
- 点击 Compare & pull request 按钮
- 填写 PR 标题和描述
- 点击 Create pull request
审核与发布
- 提交 PR 后，项目管理员会进行审核
- 如有修改意见，请在 PR 中更新你的分支
- 审核通过后，管理员会合并 PR
- 合并后网站会自动更新，你的项目将出现在展示页面上
常见问题
Q: 我不熟悉 Git，有更简单的提交方式吗？
A: 你也可以将项目资料打包发给管理员，由管理员代为提交。但我们鼓励大家学习和使用 Git，这是软件工程师的基本技能。
Q: 项目代码可以放在其他仓库吗？
A: 可以。如果代码已在其他仓库，只需在项目展示页中提供链接即可，但 sources/ 目录下至少需要一个 README.md 来说明情况。
Q: 项目截图应该是什么格式？有什么要求？
A:
- 格式：截图和图表用 PNG，实物照片用 JPG
- 尺寸：宽度不超过 1200px（建议 1080px 左右）
- 大小：单张截图 ≤ 500KB，照片 ≤ 2MB
- 内容：展示核心功能页面，包含真实数据而非空白状态
- 命名：英文小写 + 连字符，如
screenshot-dashboard.png - 详见上方 截图规范 章节
Q: 提交后多久能看到效果？
A: PR 被合并后，网站会在几分钟内自动部署更新（通过 GitHub Actions）。
需要帮助？
如果在提交过程中遇到任何问题，请联系：
- 项目管理员：GitHub Issues
- 或直接联系指导老师