162 lines
3.2 KiB
Markdown
162 lines
3.2 KiB
Markdown
---
|
||
id: development-setup
|
||
title: 开发环境设置
|
||
---
|
||
|
||
# 开发环境设置
|
||
|
||
本指南将帮助您设置 UPage 的本地开发环境，以便您可以开始贡献代码。
|
||
|
||
## 前置条件
|
||
|
||
开始开发 UPage 前，请确保您的系统满足以下要求：
|
||
|
||
- **Node.js**: 18.18.0 或更高版本
|
||
- **pnpm**: 9.4.0 或更高版本
|
||
- **Git**: 最新版本
|
||
|
||
### 安装 Node.js
|
||
|
||
您可以从 [Node.js 官网](https://nodejs.org/) 下载并安装 Node.js，或使用版本管理工具如 [nvm](https://github.com/nvm-sh/nvm)：
|
||
|
||
```bash
|
||
# 使用 nvm 安装 Node.js
|
||
nvm install 18.18.0
|
||
nvm use 18.18.0
|
||
```
|
||
|
||
### 安装 pnpm
|
||
|
||
安装 pnpm 的最简单方法是通过 npm：
|
||
|
||
```bash
|
||
npm install -g pnpm@9.4.0
|
||
```
|
||
|
||
或者按照 [pnpm 官方文档](https://pnpm.io/installation) 的说明进行安装。
|
||
|
||
## 克隆仓库
|
||
|
||
首先，[fork UPage 仓库](https://github.com/halo-dev/upage/fork)到您的 GitHub 账户，然后将其克隆到本地：
|
||
|
||
```bash
|
||
# 克隆您 fork 的仓库
|
||
git clone https://github.com/YOUR-USERNAME/upage.git
|
||
|
||
# 进入项目目录
|
||
cd upage
|
||
|
||
# 添加上游仓库
|
||
git remote add upstream https://github.com/halo-dev/upage.git
|
||
```
|
||
|
||
## 安装依赖
|
||
|
||
使用 pnpm 安装项目依赖：
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
## 生成 Prisma 客户端
|
||
|
||
UPage 使用 Prisma 作为数据库 ORM，因此需要生成 Prisma 客户端。
|
||
|
||
```bash
|
||
pnpm setup
|
||
```
|
||
|
||
## 配置环境变量
|
||
|
||
拷贝 `.env.example` 文件，创建 `.env` 文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
按照[配置参考](../configuration)的说明修改 `.env` 文件进行配置。
|
||
|
||
## 启用 Logto 认证（可选）
|
||
|
||
UPage 默认仅支持单一用户匿名访问，如果您想要开发用户认证功能，可以按照[Logto 认证集成](../deployment/logto)的说明配置 Logto 认证。
|
||
|
||
## 启动开发服务器
|
||
|
||
启动开发服务器，这将允许您在本地预览和测试您的更改：
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
此命令会启动开发服务器，您可以通过 `http://localhost:5173` 访问。
|
||
|
||
## 构建项目
|
||
|
||
要构建生产版本的项目，运行：
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
构建完成后，您可以通过以下命令预览生产版本：
|
||
|
||
```bash
|
||
pnpm preview
|
||
```
|
||
|
||
预生产版本项目运行在 `http://localhost:3000`。
|
||
|
||
## 运行测试
|
||
|
||
运行项目的测试套件：
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
## 文档开发
|
||
|
||
如果您想要修改或预览文档，可以使用以下命令：
|
||
|
||
```bash
|
||
# 启动文档开发服务器
|
||
pnpm docs:start
|
||
|
||
# 构建文档
|
||
pnpm docs:build
|
||
```
|
||
|
||
文档开发服务器默认在 `http://localhost:3000` 运行。
|
||
|
||
## 常见问题解决
|
||
|
||
### 依赖安装失败
|
||
|
||
如果您在安装依赖时遇到问题，可以尝试以下解决方案：
|
||
|
||
```bash
|
||
# 清除 pnpm 缓存
|
||
pnpm store prune
|
||
|
||
# 重新安装依赖
|
||
pnpm install --force
|
||
```
|
||
|
||
### 开发服务器启动失败
|
||
|
||
如果开发服务器无法启动，请检查：
|
||
|
||
1. 端口 5173 是否被其他应用占用
|
||
2. Node.js 版本是否符合要求
|
||
3. 是否所有依赖都已正确安装
|
||
|
||
您可以尝试使用不同的端口启动：
|
||
|
||
```bash
|
||
pnpm dev --port 5174
|
||
```
|
||
|
||
### 其他问题
|
||
|
||
如果您遇到其他问题，请查看项目的 [常见问题](../faq.md) 或在 [GitHub Issues](https://github.com/halo-dev/upage/issues) 中搜索相关问题。如果没有找到解决方案，请创建新的 issue。
|