🖼️ Loongyan Web
Loongyan 相册系统的前端应用，基于 SvelteKit 5 构建，提供现代化的相册浏览体验。
✨ 功能特性
- 📁 相册列表 - 卡片式展示所有相册
- 🖼️ 照片浏览 - 网格布局展示照片，支持预览
- 🔍 照片详情 - 查看照片完整信息和原图
- 🌍 国际化 - 支持中文/英文切换（Paraglide JS）
- 📱 响应式设计 - 适配桌面和移动设备
- ⌨️ 键盘导航 - 左右键切换照片，ESC 关闭预览
- 🎨 UI 组件库 - 可复用的组件系统
- 🔐 用户认证 - Better Auth 集成
🛠️ 技术栈
| 技术 | 说明 |
|---|---|
| Svelte 5 | 前端框架（Runes 模式） |
| SvelteKit 2 | 全栈框架 |
| Vite 7 | 构建工具 |
| Paraglide JS | 国际化 |
| Better Auth | 用户认证 |
| Drizzle ORM | 数据库 ORM |
| SQLite | 嵌入式数据库 |
| Vitest | 单元测试 |
| Playwright | 浏览器测试 |
| mdsvex | Markdown 组件 |
📁 项目结构
web/
├── src/
│ ├── lib/
│ │ ├── api/ # API 客户端
│ │ │ ├── client.js # API 请求封装
│ │ │ └── types.js # 类型定义
│ │ ├── components/ # UI 组件
│ │ │ ├── album/ # 相册组件
│ │ │ ├── photo/ # 照片组件
│ │ │ ├── layout/ # 布局组件
│ │ │ └── ui/ # 基础 UI 组件
│ │ ├── paraglide/ # 国际化生成文件
│ │ └── server/ # 服务端代码
│ │ ├── auth.js # 认证配置
│ │ └── db/ # 数据库
│ ├── routes/ # 页面路由
│ │ ├── +layout.svelte # 根布局
│ │ ├── +page.svelte # 首页（相册列表）
│ │ ├── album/[id]/ # 相册详情页
│ │ ├── photo/[id]/ # 照片详情页
│ │ └── demo/ # 演示页面
│ └── app.html # HTML 模板
├── messages/ # 国际化翻译文件
│ ├── en.json
│ └── zh.json
├── static/ # 静态资源
├── package.json
├── svelte.config.js
├── vite.config.js
└── drizzle.config.js
🚀 快速开始
环境要求
- Node.js 18+
- pnpm（推荐）或 npm
安装依赖
pnpm install
开发运行
pnpm dev
# 或自动打开浏览器
pnpm dev -- --open
开发服务器将在 http://localhost:5173 启动。
⚠️ 注意: 前端需要配合后端 API 使用。开发模式下，
/api请求会自动代理到http://localhost:8080。
构建生产版本
pnpm build
预览生产构建
pnpm preview
📡 API 配置
代理配置（开发）
开发模式下，API 请求自动代理到后端（vite.config.js）：
server: {
proxy: {
'/api': 'http://localhost:8080'
}
}
API 基础路径
API 基础路径定义在 src/lib/api/client.js：
const API_BASE = '/api/v1';
可用 API 方法
| 方法 | 说明 |
|---|---|
getAlbums() |
获取所有相册 |
getAlbum(id) |
获取相册详情 |
getAlbumPhotos(albumId) |
获取相册内照片 |
getPhoto(id) |
获取照片详情 |
getPhotoFileUrl(id) |
获取原图 URL |
getPhotoPreviewUrl(id) |
获取预览图 URL |
🧪 测试
运行测试
pnpm test
单元测试
pnpm test:unit
类型检查
pnpm check
# 监听模式
pnpm check:watch
🎨 组件库
基础 UI 组件
| 组件 | 说明 |
|---|---|
Button |
按钮组件 |
Card |
卡片容器 |
Container |
页面容器 |
Grid |
网格布局 |
Loading |
加载状态 |
Empty |
空状态提示 |
业务组件
| 组件 | 说明 |
|---|---|
AlbumCard |
相册卡片 |
AlbumList |
相册列表 |
PhotoCard |
照片卡片 |
PhotoGrid |
照片网格 |
BackLink |
返回链接 |
PageHeader |
页面标题 |
🌍 国际化
支持语言
- 🇨🇳 中文（zh）
- 🇬🇧 English（en）
翻译文件
翻译文件位于 messages/ 目录：
// messages/zh.json
{
"welcome": "欢迎"
}
// messages/en.json
{
"welcome": "Welcome"
}
使用方法
<script>
import * as m from '$lib/paraglide/messages';
</script>
<h1>{m.welcome()}</h1>
🔐 用户认证
项目集成 Better Auth，提供用户认证功能。
生成认证 Schema
pnpm auth:schema
数据库
使用 SQLite + Drizzle ORM：
# 生成迁移
pnpm drizzle-kit generate
# 执行迁移
pnpm drizzle-kit migrate
📜 脚本命令
| 命令 | 说明 |
|---|---|
pnpm dev |
启动开发服务器 |
pnpm build |
构建生产版本 |
pnpm preview |
预览生产构建 |
pnpm test |
运行测试 |
pnpm test:unit |
运行单元测试 |
pnpm check |
类型检查 |
pnpm lint |
代码检查 |
pnpm format |
格式化代码 |
pnpm auth:schema |
生成认证 Schema |
📦 部署
适配器
默认使用 @sveltejs/adapter-auto，会自动检测部署环境。
如需部署到特定平台，可安装对应适配器：
# Vercel
pnpm add -D @sveltejs/adapter-vercel
# Netlify
pnpm add -D @sveltejs/adapter-netlify
# Node.js
pnpm add -D @sveltejs/adapter-node
# 静态站点
pnpm add -D @sveltejs/adapter-static
然后在 svelte.config.js 中配置：
import adapter from '@sveltejs/adapter-node';
const config = {
kit: {
adapter: adapter()
}
};
🔗 相关链接
Made with ❤️ using SvelteKit