# 从0到1：手把手教你做一个文件分享站（附完整源码）

> 从零搭建一个支持文件夹上传、子目录管理、权限控制的文件共享系统，技术栈：Express + better-sqlite3 + 原生前端

---

## 写在前面

最近单位有个需求：需要一个内部文件共享平台，支持员工上传文件、创建文件夹、按层级管理文件，还要有审核机制。

市面上的现成方案要不太贵，要不功能过剩。于是我想：不如自己动手写一个？

花了几天时间，用 **Node.js + Express + SQLite** 搭了一个轻量级的文件分享站，支持：
- 文件和文件夹上传（含嵌套子目录）
- 文件夹层级管理
- 用户注册/登录（JWT认证）
- 文件审核机制
- 后台管理面板

![home.png](https://developer.qcloudimg.com/http-save/yehe-12702702/8c08475861522f1385ab65782ef61841.png)

今天就把整个开发过程记录下来，希望能帮到有类似需求的朋友。

---

## 一、技术选型

### 为什么选 Node.js？

1. **开发快**：Express 路由简洁，适合快速原型
2. **生态好**：multer（文件上传）、better-sqlite3（数据库）、jsonwebtoken（认证）都是成熟方案
3. **部署简单**：一个 `node server.js` 就跑起来了

### 为什么选 SQLite？

1. **零配置**：不需要安装数据库服务，一个 `.db` 文件搞定
2. **性能好**：对于文件管理类应用（几十万条记录级别），SQLite 完全够用
3. **便携**：迁移方便，备份就是一个文件拷贝

### 技术栈汇总

| 层级 | 技术 |
|------|------|
| 后端 | Node.js + Express |
| 数据库 | SQLite（better-sqlite3） |
| 认证 | JWT（jsonwebtoken） |
| 密码加密 | bcryptjs |
| 文件上传 | multer |
| 前端 | 原生 HTML/CSS/JS |

---

## 二、项目结构

```
file-share/
├── server.js          # 主服务，1140行
├── public/
│   ├── css/style.css  # 样式
│   ├── js/
│   │   ├── common.js  # 公共工具函数
│   │   ├── index.js   # 首页逻辑
│   │   └── my-files.js # 我的文件页逻辑
│   ├── login.html
│   ├── register.html
│   ├── upload.html
│   ├── my-files.html
│   └── admin.html
├── uploads/           # 文件存储目录
└── data/
    └── fileshare.db   # SQLite数据库
```

---

## 三、数据库设计

核心就是三张表：`users`、`files`、`settings`

```sql
-- 用户表
CREATE TABLE users (
  id            TEXT PRIMARY KEY,
  username      TEXT UNIQUE NOT NULL,
  displayName   TEXT NOT NULL,
  passwordHash  TEXT NOT NULL,
  role          TEXT NOT NULL DEFAULT 'user',
  status        TEXT NOT NULL DEFAULT 'active',
  createdAt     TEXT NOT NULL
);

-- 文件表
CREATE TABLE files (
  id                  TEXT PRIMARY KEY,
  code                TEXT UNIQUE NOT NULL,   -- 分享码
  originalName        TEXT NOT NULL,
  size                INTEGER NOT NULL,
  mimeType            TEXT,
  storedName          TEXT NOT NULL,          -- 服务器存储名
  uploadDate          TEXT NOT NULL,
  uploaderId          TEXT NOT NULL,
  uploaderName        TEXT NOT NULL,
  uploaderDisplayName TEXT NOT NULL,
  status              TEXT NOT NULL DEFAULT 'pending',
  downloads           INTEGER NOT NULL DEFAULT 0,
  batchId             TEXT DEFAULT '',        -- 文件夹ID
  folderPath          TEXT DEFAULT ''         -- 文件路径（如 folder/sub/file.txt）
);

-- 网站设置表
CREATE TABLE settings (
  key   TEXT PRIMARY KEY,
  value TEXT
);
```

**关键设计点：**
- `batchId`：同一文件夹的所有文件共享同一个 batchId
- `folderPath`：存储相对路径，支持嵌套子目录（如 `抽查表/geek/test.txt`）

---

## 四、核心功能实现

### 4.1 文件上传

使用 multer 处理文件上传，支持单个文件和文件夹：

```javascript
const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, UPLOAD_DIR),
  filename: (req, file, cl) => {
    const ext = path.extname(file.originalname);
    cl(null, `${crypto.randomUUID()}${ext}`);
  }
});

const upload = multer({ storage });

// 单文件上传
app.post('/api/upload', auth, upload.single('file'), (req, res) => {
  const record = {
    id: crypto.randomUUID(),
    code: crypto.randomBytes(4).toString('hex'),
    originalName: Buffer.from(req.file.originalname, 'latin1').toString('utf8'),
    // ... 其他字段
    batchId: req.body.batchId || '',
    folderPath: req.body.folderPath || ''
  };
  S.insertFile.run(record);
  res.json({ file: publicFileMeta(record) });
});
```

**中文文件名处理：**
```javascript
Buffer.from(originalname, 'latin1').toString('utf8')
```
multer 默认用 latin1 解码，需要转换回 UTF-8。

### 4.2 JWT 认证

```javascript
// 登录
app.post('/api/auth/login', async (req, res) => {
  const user = S.getUserByName.get(req.body.username);
  if (!user || !await bcrypt.compare(req.body.password, user.passwordHash)) {
    return res.status(401).json({ error: '用户名或密码错误' });
  }
  const token = jwt.sign({ id: user.id }, JWT_SECRET, { expiresIn: '7d' });
  res.json({ token, user: sanitizeUser(user) });
});

// 认证中间件
function auth(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: '请先登录' });
  try {
    req.user = jwt.verify(token, JWT_SECRET);
    next();
  } catch {
    res.status(401).json({ error: '令牌无效' });
  }
}
```

### 4.3 文件夹与子目录管理

这是整个项目的核心难点。关键在于 **folderPath 的设计**：

```
抽查表/
├── 3.11早操抽查.xlsx          (folderPath: 抽查表/3.11早操抽查.xlsx)
└── geek/
    ├── geek.exe               (folderPath: 抽查表/geek/geek.exe)
    └── test-file.txt          (folderPath: 抽查表/geek/test-file.txt)
```

#### 重命名子文件夹

```javascript
app.patch('/api/folder/:batchId/rename-subfolder', auth, (req, res) => {
  const { oldName, newName } = req.body;
  const sourceBatchId = req.params.batchId;
  
  const batchFiles = S.getByBatch.all(sourceBatchId);
  const sourceTopFolder = (batchFiles[0].folderPath || '').split('/')[0];
  const fullPrefix = `${sourceTopFolder}/${oldName}/`;
  
  db.transaction(() => {
    batchFiles.forEach(f => {
      if (f.folderPath.startsWith(fullPrefix)) {
        const newPath = fullPrefix.replace(oldName, newName) + f.folderPath.substring(fullPrefix.length);
        S.updateFolderPath.run(newPath, f.id);
      }
    });
  })();
});
```

**关键点**：必须用完整路径前缀匹配，不能用 `oldName + '/'`。

#### 移动子文件夹

```javascript
app.patch('/api/folder/:batchId/move-subfolder', auth, (req, res) => {
  const { subFolderName, targetBatchId } = req.body;
  
  const batchFiles = S.getByBatch.all(sourceBatchId);
  const sourceTopFolder = (batchFiles[0].folderPath || '').split('/')[0];
  const fullPrefix = `${sourceTopFolder}/${subFolderName}/`;
  
  const tx = db.transaction(() => {
    batchFiles.forEach(f => {
      if (f.folderPath.startsWith(fullPrefix)) {
        const rest = f.folderPath.substring(fullPrefix.length);
        const newPath = `${targetFolderName}/${subFolderName}/${rest}`;
        S.updateFileFolder.run(targetId, newPath, f.id);
      }
    });
  });
  tx();
});
```

### 4.4 文件审核机制

文件上传后默认状态为 `pending`，需要管理员审核后才能在首页展示：

```javascript
// 我的文件 - 全部可见
app.get('/api/my-files', auth, (req, res) => {
  const rows = S.getMine.all(req.user.id);
  // ...
});

// 公开文件 - 仅已审核
app.get('/api/files', (req, res) => {
  const rows = S.getApproved.all();
  // ...
});
```

### 4.5 前端渲染逻辑

#### 文件夹树渲染

```javascript
function renderFolderTreeHtml(files, topName, renderFile, mode, parentBatchId) {
  function buildHtml(list, currentBatchId) {
    const directFiles = [];
    const subMap = new Map();
    
    list.forEach(({ f, rel }) => {
      const slash = rel.indexOf('/');
      if (slash < 0) {
        directFiles.push({ f });
      } else {
        const sub = rel.substring(0, slash);
        const rest = rel.substring(slash + 1);
        if (!subMap.has(sub)) subMap.set(sub, []);
        subMap.get(sub).push({ f, rel: rest });
      }
    });
    
    let html = directFiles.map(({ f }) => renderFile(f)).join('');
    
    subMap.forEach(([sub, children]) => {
      const editBtn = currentBatchId
        ? `<button class="btn btn-ghost btn-sm edit-subfolder-btn" 
                   data-batch-id="${currentBatchId}" 
                   data-sub-name="${escapeHtml(sub)}">编辑</button>`
        : '';
      // 递归渲染子目录
      html += `<div class="folder-subgroup">${editBtn}${buildHtml(children, currentBatchId)}</div>`;
    });
    
    return html;
  }
  
  return buildHtml(items, parentBatchId);
}
```

---

## 五、遇到的问题与解决方案

### 5.1 路径匹配错误

最初写子文件夹重命名时，用的是：
```javascript
const prefix = oldName + '/';  // ❌ 错误
if (oldPath.startsWith(prefix)) { ... }
```

但数据库中存储的是完整路径 `抽查表/geek/test.txt`，所以 `startsWith('geek/')` 永远返回 false。

**修复**：提取顶层文件夹名，构建完整前缀：
```javascript
const sourceTopFolder = (batchFiles[0].folderPath || '').split('/')[0];
const fullPrefix = `${sourceTopFolder}/${oldName}/`;  // ✓ 正确
```

### 5.2 批处理文件编码问题

restart.bat 无法正确读取 .env 文件中的端口配置，因为 Windows 的 cmd 默认用 GBK 编码。

**修复**：将 .env 文件转为 ASCII 编码，注释也改用英文：
```
# File Share Site Config
# Change PORT and restart to take effect
PORT=8080
JWT_SECRET=x7K9mP2vQ8wR4nL6jY3bN5cZ1fT0hD
```

### 5.3 SQLite WAL 模式

默认模式下高并发会有写入冲突，开启 WAL 模式后性能提升明显：
```javascript
db.pragma('journal_mode = WAL');
db.pragma('foreign_keys = ON');
```

---

## 六、性能优化建议

1. **索引优化**：给 `batchId`、`status`、`uploaderId` 加索引
2. **分页查询**：文件量大时按需分页
3. **静态资源缓存**：设置适当的 Cache-Control
4. **文件清理**：定期清理孤立文件（没有对应数据库记录的文件）

---

## 七、部署方式

### 方式一：直接运行（测试环境）
```bash
npm install
node server.js
# 访问 http://localhost:8080
```

### 方式二：PM2 守护进程
```bash
npm install -g pm2
pm2 start server.js --name file-share
pm2 save
pm2 startup  # 开机自启
```

### 方式三：Docker 容器化
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 8080
CMD ["node", "server.js"]
```

---

## 八、总结

这个项目虽然代码量不大（约 4000 行），但涵盖了文件管理系统的主要功能点：

- 文件上传与存储
- 文件夹层级管理
- 用户认证与授权
- 审核工作流
- 中文文件名处理

如果你也有类似的需求，不妨从头写一个，过程中会遇到很多有趣的技术挑战。

**完整源码已开源**，欢迎 star 和提 issue！

---

*作者：WorkBuddy AI Assistant*
*原文链接：https://workbuddy.cn*


从零搭建一个支持文件夹上传、子目录管理、权限控制的文件共享系统，技术栈：Express + better-sqlite3 + 原生前端

从0到1：手把手教你做一个文件分享站（附完整源码）

后端

开发工具

编程语言

基于Express+better-sqlite3构建的轻量级文件分享系统，支持文件夹嵌套上传、子目录管理、JWT用户认证、文件审核机制及后台管理面板，提供完整源码与部署方案。

文件存储

代码解释

中间件

数据库

服务器

Windows

容器

路由

SQLite

2026上云采购 | AI焕新·智启新局

tencentdb-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

从0到1：手把手教你做一个文件分享站（附完整源码）-腾讯云开发者社区-腾讯云

从0到1：手把手教你做一个文件分享站（附完整源码）

从0到1：手把手教你做一个文件分享站（附完整源码）

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐