Express

Express 是一个轻量级、灵活的 Node.js Web 框架，以其简单易用和高度可扩展著称。它提供了简洁的 API 设计，支持中间件机制，能快速构建 RESTful API 或全栈应用。Express 拥有丰富的插件生态，可轻松集成数据库、身份验证等功能，同时保持高性能和低学习成本，是 Node.js 开发者的首选框架之一。

本指南介绍如何在 CloudBase HTTP 云函数上部署 Express 应用程序。

前置条件

在开始之前，请确保您已经：

• 安装了 Node.js 18.x 或更高版本
• 拥有腾讯云账号并开通了 CloudBase 服务
• 了解基本的 Node.js 和 Express 开发知识

第一步：创建 Express 应用

💡 提示：如果您已经有一个 Express 应用，可以跳过此步骤。

创建项目目录

mkdir express-cloudbase
cd express-cloudbase

使用 Express Generator 创建应用

# 使用 Express Generator 创建应用
npx express-generator --view=pug express-app

# 进入项目目录
cd express-app

# 安装依赖
npm install

这将创建一个使用 Pug 作为视图引擎的 Express 应用程序。

本地测试应用

启动开发服务器：

npm start

打开浏览器访问 http://localhost:3000，您应该能看到 Express 欢迎页面。

第二步：添加 API 路由

让我们创建一个 RESTful API 来演示 Express 的功能。

创建用户路由

在 routes 目录下创建 users.js 文件：

const express = require('express');
const router = express.Router();

// 模拟用户数据
const users = [
  { id: 1, name: 'zhangsan', email: 'zhangsan@example.com' },
  { id: 2, name: 'lisi', email: 'lisi@example.com' },
  { id: 3, name: 'wangwu', email: 'wangwu@example.com' }
];

/* GET users listing */
router.get('/', function(req, res, next) {
  const { page = 1, limit = 10 } = req.query;
  const startIndex = (page - 1) * limit;
  const endIndex = startIndex + parseInt(limit);
  
  const paginatedUsers = users.slice(startIndex, endIndex);
  
  res.json({
    success: true,
    data: {
      total: users.length,
      page: parseInt(page),
      limit: parseInt(limit),
      items: paginatedUsers
    }
  });
});

/* GET user by ID */
router.get('/:id', function(req, res, next) {
  const userId = parseInt(req.params.id);
  const user = users.find(u => u.id === userId);
  
  if (!user) {
    return res.status(404).json({
      success: false,
      message: 'User not found'
    });
  }
  
  res.json({
    success: true,
    data: user
  });
});

/* POST create user */
router.post('/', function(req, res, next) {
  const { name, email } = req.body;
  
  if (!name || !email) {
    return res.status(400).json({
      success: false,
      message: 'Name and email are required'
    });
  }
  
  const newUser = {
    id: users.length + 1,
    name,
    email
  };
  
  users.push(newUser);
  
  res.status(201).json({
    success: true,
    data: newUser
  });
});

module.exports = router;

创建健康检查路由

在 routes 目录下创建 health.js 文件：

const express = require('express');
const router = express.Router();

/* GET health check */
router.get('/', function(req, res, next) {
  res.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    framework: 'Express',
    version: process.env.npm_package_version || '1.0.0',
    node_version: process.version
  });
});

module.exports = router;

更新应用配置

编辑 app.js 文件，添加新的路由和中间件：

var createError = require('http-errors');
var express = require('express');
var path = require('path');
var cookieParser = require('cookie-parser');
var logger = require('morgan');

var indexRouter = require('./routes/index');
var usersRouter = require('./routes/users');
var healthRouter = require('./routes/health');

var app = express();

// view engine setup
app.set('views', path.join(__dirname, 'views'));
app.set('view engine', 'pug');

app.use(logger('combined'));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, 'public')));

// 路由配置
app.use('/', indexRouter);
app.use('/api/users', usersRouter);
app.use('/health', healthRouter);

// 404 错误处理
app.use(function(req, res, next) {
  next(createError(404));
});

// 全局错误处理
app.use(function(err, req, res, next) {
  // 设置错误信息，只在开发环境提供详细错误
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // 返回 JSON 格式的错误信息
  if (req.path.startsWith('/api/') || req.path.startsWith('/health')) {
    res.status(err.status || 500).json({
      success: false,
      message: err.message,
      error: req.app.get('env') === 'development' ? err.stack : undefined
    });
  } else {
    // 渲染错误页面
    res.status(err.status || 500);
    res.render('error');
  }
});

module.exports = app;

修改启动配置

编辑 bin/www 文件，确保应用监听正确的端口：

#!/usr/bin/env node

/**
 * Module dependencies.
 */

var app = require('../app');
var debug = require('debug')('express-app:server');
var http = require('http');

/**
 * Get port from environment and store in Express.
 */

var port = normalizePort(process.env.PORT || '9000');
app.set('port', port);

/**
 * Create HTTP server.
 */

var server = http.createServer(app);

/**
 * Listen on provided port, on all network interfaces.
 */

server.listen(port, '0.0.0.0');
server.on('error', onError);
server.on('listening', onListening);

/**
 * Normalize a port into a number, string, or false.
 */

function normalizePort(val) {
  var port = parseInt(val, 10);

  if (isNaN(port)) {
    // named pipe
    return val;
  }

  if (port >= 0) {
    // port number
    return port;
  }

  return false;
}

/**
 * Event listener for HTTP server "error" event.
 */

function onError(error) {
  if (error.syscall !== 'listen') {
    throw error;
  }

  var bind = typeof port === 'string'
    ? 'Pipe ' + port
    : 'Port ' + port;

  // handle specific listen errors with friendly messages
  switch (error.code) {
    case 'EACCES':
      console.error(bind + ' requires elevated privileges');
      process.exit(1);
      break;
    case 'EADDRINUSE':
      console.error(bind + ' is already in use');
      process.exit(1);
      break;
    default:
      throw error;
  }
}

/**
 * Event listener for HTTP server "listening" event.
 */

function onListening() {
  var addr = server.address();
  var bind = typeof addr === 'string'
    ? 'pipe ' + addr
    : 'port ' + addr.port;
  debug('Listening on ' + bind);
  console.log('Express server listening on ' + bind);
}

第三步：本地测试

⚠️ 重要提示：CloudBase HTTP 云函数要求应用监听 9000 端口。

启动应用：

npm start

测试 API 接口：

# 测试健康检查
curl http://localhost:9000/health

# 测试用户列表
curl http://localhost:9000/api/users

# 测试分页
curl "http://localhost:9000/api/users?page=1&limit=2"

# 测试获取单个用户
curl http://localhost:9000/api/users/1

# 测试创建用户
curl -X POST http://localhost:9000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"新用户","email":"newuser@example.com"}'

第四步：创建启动脚本

创建 scf_bootstrap 文件（无扩展名）：

#!/bin/bash
export PORT=9000
npm start

为启动脚本添加执行权限：

chmod +x scf_bootstrap

💡 说明：

• scf_bootstrap 是 CloudBase 云函数的启动脚本
• 设置 PORT=9000 环境变量确保应用监听正确端口
• 使用 npm start 启动应用

第五步：准备部署文件

确保您的项目目录结构如下：

express-app/
├── bin/
│   └── www                 # 启动文件
├── public/                 # 静态资源
├── routes/                 # 路由文件
│   ├── index.js
│   ├── users.js
│   └── health.js
├── views/                  # 视图模板
├── app.js                  # 应用主文件
├── package.json           # 项目配置
├── package-lock.json      # 依赖锁定文件
└── scf_bootstrap         # 启动脚本

第六步：部署到 CloudBase HTTP 云函数

通过控制台部署

1. 登录 CloudBase 控制台
2. 选择您的环境，进入「云函数」页面
3. 点击「新建云函数」
4. 选择「HTTP 云函数」
5. 填写函数名称（如：express-app）
6. 选择运行时：Node.js 18.x（或其他支持的版本）
7. 提交方法选择：本地上传文件夹
8. 函数代码选择 express-app 目录进行上传
9. 自动安装依赖：开启此选项
10. 点击「创建」按钮等待部署完成

通过 CLI 部署(敬请期待)

打包部署

如果需要手动打包：

# 创建部署包（排除开发文件）
zip -r express-app.zip . -x "node_modules/*" ".git/*" "*.log"

第七步：访问您的应用

部署成功后，您可以参考通过 HTTP 访问云函数设置自定义域名访问HTTP 云函数。

您可以测试以下接口：

• 根路径：/ - Express 欢迎页面
• 健康检查：/health - 查看应用状态
• 用户列表：/api/users - 获取用户列表
• 用户详情：/api/users/1 - 获取特定用户
• 创建用户：POST /api/users - 创建新用户

常见问题

Q: 为什么必须使用 9000 端口？

A: CloudBase HTTP 云函数要求应用监听 9000 端口，这是平台的标准配置。

Q: 如何处理静态文件？

A: Express 的静态文件中间件会自动处理 public 目录下的静态资源。

Q: 如何查看应用日志？

A: 在 CloudBase 控制台的云函数页面，点击函数名称进入详情页查看运行日志。

Q: 支持哪些 Node.js 版本？

A: CloudBase 支持 Node.js 16.x、18.x、20.x 等版本，建议使用最新的 LTS 版本。

Q: 如何处理 CORS 跨域问题？

A: 可以使用 cors 中间件或手动设置响应头来处理跨域请求。

最佳实践

1. 环境变量管理

在 app.js 中添加环境变量支持：

// 加载环境变量
require('dotenv').config();

// 使用环境变量
const isDevelopment = process.env.NODE_ENV === 'development';
const port = process.env.PORT || 9000;

2. 添加 CORS 支持

安装并配置 CORS 中间件：

npm install cors

const cors = require('cors');

// 配置 CORS
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  credentials: true
}));

3. 请求日志

使用 Morgan 中间件记录请求日志：

const morgan = require('morgan');

// 配置日志格式
app.use(morgan(process.env.NODE_ENV === 'production' ? 'combined' : 'dev'));

4. 错误处理

实现全局错误处理中间件：

// 全局错误处理
app.use((err, req, res, next) => {
  console.error(err.stack);
  
  res.status(err.status || 500).json({
    success: false,
    message: err.message,
    ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
  });
});

5. 安全配置

安装并配置 Helmet 中间件：

npm install helmet

const helmet = require('helmet');

// 安全头配置
app.use(helmet());

进阶功能

数据库集成

集成 MongoDB 或 MySQL：

npm install mongoose
# 或
npm install mysql2

身份验证

添加 JWT 身份验证：

npm install jsonwebtoken bcryptjs

API 文档

使用 Swagger 生成 API 文档：

npm install swagger-jsdoc swagger-ui-express

下一步

• 了解更多 HTTP 云函数配置选项
• 学习如何 连接 CloudBase 数据库