send API完全参考：掌握配置选项与事件处理的实战指南

send API完全参考：掌握配置选项与事件处理的实战指南

【免费下载链接】sendStreaming static file server with Range and conditional-GET support项目地址: https://gitcode.com/gh_mirrors/send/send

send是一个功能强大的静态文件流服务器，提供Range和条件GET支持，帮助开发者轻松构建高效的文件传输服务。本指南将全面解析send API的配置选项和事件处理机制，助你快速掌握其核心功能与实战应用。

快速入门：安装与基础使用

一键安装步骤

通过npm即可完成send的安装：

npm install send

基础用法示例

以下是一个简单的send服务示例，展示如何创建一个基础的文件服务器：

const http = require('http'); const send = require('send'); const path = require('path'); const server = http.createServer((req, res) => { send(req, req.url, { root: path.join(__dirname, 'public') }) .pipe(res) .on('error', (err) => { res.statusCode = err.status || 500; res.end(err.message); }); }); server.listen(3000, () => { console.log('Server running on port 3000'); });

核心配置选项详解

root：设置文件根目录

root选项用于指定文件服务的根目录，确保文件路径安全可控。

send(req, '/files/image.jpg', { root: '/path/to/your/files' })

安全提示：始终设置root选项以防止路径遍历攻击，如index.js所示。

maxAge：配置缓存策略

通过maxAge选项设置缓存过期时间，单位为毫秒，帮助优化客户端加载性能：

send(req, '/style.css', { maxAge: 3600000 }) // 缓存1小时

send会自动处理Cache-Control头，如index.js中的实现。

dotfiles：处理隐藏文件

控制如何处理以点开头的隐藏文件，可选值为allow、deny或ignore：

// 允许访问隐藏文件 send(req, '/.env', { dotfiles: 'allow' })

默认配置为ignore，会返回404错误，详见index.js。

extensions：自动添加文件扩展名

当请求的文件不存在时，自动尝试添加指定的扩展名：

// 尝试请求file、file.html、file.txt send(req, '/file', { extensions: ['html', 'txt'] })

实现逻辑可参考index.js。

etag与lastModified：启用条件请求

send默认启用ETag和Last-Modified头，优化网络传输：

send(req, '/data.json', { etag: true, lastModified: true })

相关实现见index.js。

事件处理机制

error事件：错误处理

捕获并处理文件传输过程中的错误：

send(req, '/missing-file.html') .on('error', (err) => { console.error('传输错误:', err); res.statusCode = err.status || 500; res.end('文件传输失败'); }) .pipe(res);

错误处理逻辑在index.js中定义。

file事件：文件找到通知

当找到请求的文件时触发，可用于记录访问日志：

send(req, '/report.pdf') .on('file', (path, stat) => { console.log(`正在传输文件: ${path}, 大小: ${stat.size} bytes`); }) .pipe(res);

stream事件：获取可读流

获取文件的可读流，进行自定义处理：

send(req, '/video.mp4') .on('stream', (stream) => { // 对视频流进行处理，如添加水印 stream.pipe(watermarkTransform).pipe(res); });

流处理实现见index.js。

高级功能实战

Range请求支持

send自动支持HTTP Range请求，实现断点续传功能：

GET /large-file.zip HTTP/1.1 Range: bytes=0-999

服务器会返回206 Partial Content响应，相关实现见index.js。

条件GET请求

通过If-Modified-Since和If-None-Match头实现缓存验证：

GET /app.js HTTP/1.1 If-Modified-Since: Wed, 21 Oct 2023 07:28:00 GMT

未修改时返回304 Not Modified，详见index.js。

目录索引功能

配置index选项实现目录浏览：

send(req, '/docs/', { index: ['index.html', 'README.md'] })

当请求目录时，send会自动尝试加载指定的索引文件，实现逻辑见index.js。

最佳实践与注意事项

安全配置建议

• 始终设置root选项限制文件访问范围
• 使用dotfiles: 'deny'防止访问敏感隐藏文件
• 避免将send直接暴露到公网，建议配合反向代理使用

性能优化技巧

• 合理设置maxAge利用客户端缓存
• 对大文件启用Range请求支持断点续传
• 使用gzip压缩减少传输体积（需配合其他中间件）

常见问题解决

• 403错误：检查文件权限或dotfiles配置
• 416错误：客户端请求的Range无效，确保文件大小正确
• 缓存问题：使用ETag和Last-Modified确保缓存有效性

总结

send作为一个轻量级但功能强大的静态文件服务库，通过简洁的API提供了丰富的文件传输功能。无论是构建简单的静态网站还是复杂的文件下载服务，send都能满足你的需求。通过合理配置选项和事件处理，你可以轻松实现高效、安全的文件传输服务。

要获取更多示例和详细文档，请查看项目的测试文件test/send.js，其中包含了各种功能的使用案例。现在就开始使用send，提升你的文件服务体验吧！

【免费下载链接】sendStreaming static file server with Range and conditional-GET support项目地址: https://gitcode.com/gh_mirrors/send/send