143 lines
2.4 KiB
Markdown
143 lines
2.4 KiB
Markdown
# 开发环境搭建
|
||
|
||
**文档版本**: 1.0.0
|
||
**最后更新**: 2026-04-19
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [环境要求](#1-环境要求)
|
||
2. [<!-- 模块1 -->环境](#2-模块1环境)
|
||
3. [<!-- 模块2 -->环境](#3-模块2环境)
|
||
4. [IDE 配置](#4-ide-配置)
|
||
5. [常见问题](#5-常见问题)
|
||
|
||
---
|
||
|
||
## 1. 环境要求
|
||
|
||
### 1.1 操作系统
|
||
|
||
- <!-- 操作系统要求 -->
|
||
|
||
### 1.2 基础依赖
|
||
|
||
| 工具 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| <!-- 工具 --> | <!-- 版本 --> | <!-- 用途 --> |
|
||
|
||
### 1.3 镜像源配置
|
||
|
||
国内开发环境建议配置镜像源（详见 [`team/mirrors.md`](../team/mirrors.md)）。
|
||
|
||
---
|
||
|
||
## 2. <!-- 模块1 -->环境
|
||
|
||
### 2.1 克隆与安装
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
jj git clone <!-- 仓库地址 -->
|
||
cd <!-- 项目目录 -->
|
||
|
||
# 安装依赖
|
||
cd apps/<!-- 模块 -->
|
||
uv sync
|
||
```
|
||
|
||
### 2.2 开发服务器启动
|
||
|
||
```bash
|
||
cd apps/<!-- 模块 -->
|
||
uv run <!-- 启动命令 -->
|
||
```
|
||
|
||
### 2.3 数据库初始化
|
||
|
||
> 待编写
|
||
|
||
---
|
||
|
||
## 3. <!-- 模块2 -->环境
|
||
|
||
### 3.1 <!-- 环境说明 -->
|
||
|
||
```bash
|
||
# 安装依赖
|
||
cd apps/<!-- 模块 -->
|
||
uv sync
|
||
|
||
# 启动
|
||
uv run <!-- 启动命令 -->
|
||
```
|
||
|
||
---
|
||
|
||
## 4. IDE 配置
|
||
|
||
### 4.1 VS Code 推荐扩展
|
||
|
||
```json
|
||
{
|
||
"recommendations": [
|
||
"charliermarsh.ruff",
|
||
"ms-python.mypy-type-checker",
|
||
"ms-python.python"
|
||
]
|
||
}
|
||
```
|
||
|
||
| 扩展 | 用途 |
|
||
|------|------|
|
||
| **Ruff** | Python 格式化 + Lint |
|
||
| **mypy Type Checker** | Python 类型检查 |
|
||
| **Python** | Python 语言支持、调试 |
|
||
|
||
### 4.2 代码格式化与 Lint
|
||
|
||
- 格式化：`ruff format`
|
||
- Lint：`ruff check`
|
||
- 类型检查：`mypy --strict`
|
||
|
||
### 4.3 调试配置
|
||
|
||
> 待编写
|
||
|
||
---
|
||
|
||
## 5. 常见问题
|
||
|
||
### 5.1 Python 环境问题
|
||
|
||
**Q: `uv sync` 安装依赖失败**
|
||
A: 检查 Python 版本是否符合要求，并确认镜像源配置正确。
|
||
|
||
**Q: `mypy --strict` 报大量错误**
|
||
A: 项目强制 mypy strict 模式，禁止 `Any` 类型。确保所有函数和变量都有完整类型注解。
|
||
|
||
### 5.2 前端环境问题
|
||
|
||
> 待编写
|
||
|
||
### 5.3 数据库问题
|
||
|
||
**Q: Schema 迁移失败**
|
||
A: 迁移前会自动备份。恢复方法：
|
||
```bash
|
||
cp backups/backup_v{N}.db data/<!-- 数据库文件 -->
|
||
```
|
||
|
||
### 5.4 版本控制问题
|
||
|
||
**Q: jj 和 git 命令如何选择**
|
||
A: 项目默认使用 jj。常用命令对照见 [`team/jj.md`](../team/jj.md)。
|
||
|
||
> 更多运行时故障排除见 [`运维-故障排除.md`](./运维-故障排除.md)。
|
||
|
||
---
|
||
|
||
**版本历史**:
|
||
- v1.0.0 (2026-04-19): 初始化模板
|