使用文档

🚀 快速开始

环境要求

• Node.js 18.0 或更高版本
• pnpm（推荐）或 npm
• 现代浏览器支持

快速安装

# 克隆项目
git clone https://github.com/your-username/finder-web.git
cd finder-web

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

访问 http://localhost:3000 开始使用。

📦 安装配置

1. 下载项目

git clone https://github.com/your-username/finder-web.git

2. 安装依赖

# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install

3. 配置浏览模式

复制环境变量配置文件并根据需要修改：

cp .env.example .env.local

编辑 .env.local 文件选择浏览模式：

# 本地文件系统模式
FILE_BROWSER_MODE=local
ROOT_PATH=/Users/your-username/Documents

# 或项目文件夹模式
FILE_BROWSER_MODE=files
FILES_MODE_ENABLED=true
FILES_FOLDER_PATH=files

⚙️ 配置说明

浏览模式配置

FILE_BROWSER_MODE=local
ROOT_PATH=/Users/your-username/Documents

# 开发环境
FILE_BROWSER_MODE=files
FILES_MODE_ENABLED=true
FILES_FOLDER_PATH=files

# 生产环境（Vercel 等）
FILE_BROWSER_MODE=files
FILES_MODE_ENABLED=true
FILES_FOLDER_PATH=public/files

性能配置

• 文本文件大小限制: 1MB（可在 config/app.config.ts 中修改）
• CSV 显示行数: 普通模式 10 行，展开模式 50 行
• 代码高亮最大高度: 普通模式 384px，展开模式无限制

环境检测配置

项目支持自动环境检测，根据部署环境选择合适的文件系统模式：

• 开发环境: 使用 Node.js fs 模块直接读取文件系统
• Vercel 部署: 自动检测 VERCEL=1 环境变量，使用静态文件列表
• 生产环境: NODE_ENV=production 时使用静态文件列表
• 构建时生成: prebuild 脚本自动扫描文件并生成 JSON 列表

安全配置

• 路径验证: 严格限制文件访问范围
• 文件类型检查: 只允许预览安全的文件类型
• 大小限制: 自动跳过过大文件的内容读取

🚀 部署指南

构建生产版本

# 构建项目
pnpm build

# 启动生产服务器
pnpm start

Docker 部署

# 构建 Docker 镜像
docker build -t finder-web .

# 运行容器 - 项目文件夹模式（推荐）
docker run -p 3000:3000 -v /your/local/files:/app/files finder-web

# 运行容器 - 本地文件系统模式
docker run -p 3000:3000 \
  -v /your/local/directory:/app/mounted \
  -e FILE_BROWSER_MODE=local \
  -e ROOT_PATH=/app/mounted \
  finder-web

Vercel 部署

项目已配置好 Vercel 部署支持，包含自动环境检测和静态文件生成。

快速部署

点击下方按钮一键部署到 Vercel：

手动部署步骤

1. 1. 将代码推送到 GitHub 仓库
2. 2. 在 Vercel 中导入项目
3. 3. 配置环境变量（见下方）
4. 4. 点击部署

Vercel 环境变量配置

FILE_BROWSER_MODE=files
FILES_MODE_ENABLED=true
FILES_FOLDER_PATH=public/files

部署特性

• • 自动环境检测：根据部署环境自动选择文件系统模式
• • 静态文件生成：构建时自动扫描并生成文件列表
• • 无服务器兼容：完全兼容 Vercel 的 serverless 环境
• • CDN 加速：静态文件通过 Vercel CDN 加速访问