Modern.js 项目部署指南：从基础到进阶

Modern.js 作为一个现代化的 Web 开发框架，提供了多种灵活的部署方案。本文将全面介绍如何将 Modern.js 项目部署到不同环境，包括 Node.js 服务器、Netlify 和 Vercel 平台，并针对不同项目结构（单仓库和 Monorepo）提供详细的部署指导。

一、Modern.js 部署概览

Modern.js 目前支持两种主要部署方式：

1. 自主托管部署：将应用部署在包含 Node.js 环境的容器中，这种方式提供了最大的灵活性
2. 平台部署：目前支持 Netlify 和 Vercel 两大主流平台

需要注意的是，当前版本 Modern.js 仅支持在 Node.js 环境中运行，未来版本将支持更多运行时环境。

二、构建部署产物

Modern.js 提供了 modern deploy 命令来自动生成部署产物。这个命令会：

1. 优化 Bundler 构建产物及其依赖
2. 检测当前部署平台
3. 自动生成适合该平台的部署产物

如果想为特定平台生成并测试输出，可以通过设置环境变量指定平台：

MODERNJS_DEPLOY=netlify npx modern deploy

对于 Modern.js 官方支持的部署平台，通常不需要手动指定环境变量。

三、Node.js 环境部署

3.1 单仓库项目部署

当未检测到 Modern.js 支持的部署平台时，Modern.js 会默认输出可在 Node.js 环境中运行的构建产物。

部署步骤：

1. 运行构建命令：

npx modern deploy

2. 命令执行后，Modern.js 会生成可运行产物，并在终端输出以下信息：

Static directory: `.output/static`
You can preview this build by `node .output/index`

3. 运行服务器：

node .output/index

4. 页面所需的静态资源位于 .output/static 目录，可自行上传至 CDN

注意事项：

• 默认监听端口为 8080
• 可通过 PORT 环境变量修改监听端口：

PORT=3000 node .output/index

3.2 Monorepo 项目部署

对于 Monorepo 项目，除了构建当前项目外，还需要构建当前项目依赖的其他子项目。

使用 pnpm 的配置示例

假设当前项目名为 app，在 package.json 中添加：

{
  "scripts": {
    "build:packages": "pnpm --filter 'app^...' run build",
    "deploy": "pnpm run build:packages && modern deploy",
  }
}

使用 Rush 的配置示例

{
  "scripts": {
    "build:packages": "rush rebuild --to-except app",
    "deploy": "rushx build:packages && modern deploy",
  }
}

构建完成后，Modern.js 会在项目的 .output/node_modules 目录中生成所有依赖，同样可以使用 node .output/index 运行服务器。

四、Netlify 平台部署

Netlify 是一个流行的 Web 开发平台，专为构建、部署和维护现代 Web 项目而设计。

4.1 纯前端项目部署

1. 在项目根目录创建 netlify.toml 文件
2. 添加以下内容：

[build]
  publish = "dist"
  command = "modern deploy"

3. 在 Netlify 平台上添加项目并部署

4.2 全栈项目部署

全栈项目指使用 Custom Web Server、SSR 或 BFF 的项目，这些项目需要部署在 Netlify Functions 上。

配置示例：

[build]
  publish = "dist"
  command = "modern deploy"

[functions]
  directory = ".netlify/functions"
  node_bundler = "none"
  included_files = [".netlify/functions/**"]

注意：当前版本不支持 Netlify Edge Functions，将在未来版本中支持。

4.3 Monorepo 项目部署

假设项目结构如下：

.
├── packages
│   ├── app
│   └── app-dep1
├── package.json
└── pnpm-workspace.yaml

部署步骤：

1. 在 Netlify 平台配置 Base directory 为 packages/app
2. 在 packages/app/package.json 中添加：

{
  "scripts": {
    "build:packages": "pnpm --filter 'app^...' run build",
    "deploy": "pnpm run build:packages && modern deploy",
  }
}

3. 配置 netlify.toml：

[build]
  publish = "dist"
  command = "npm run deploy"

[functions]
  directory = ".netlify/functions"
  node_bundler = "none"
  included_files = [".netlify/functions/**"]

五、Vercel 平台部署

Vercel 是另一个流行的现代 Web 应用部署平台，支持静态网站、服务端渲染应用等多种部署场景。

5.1 纯前端项目部署

1. 在项目根目录创建 vercel.json 文件
2. 添加以下内容：

{
  "buildCommand": "modern deploy",
  "outputDirectory": ".vercel/output"
}

3. 在 Vercel 平台选择 Framework Preset 为 Other 并部署

5.2 全栈项目部署

全栈项目需要部署在 Vercel Functions 上，注意事项：

1. 当前版本不支持在 Vercel 平台部署 BFF 项目
2. 建议使用 Node.js 18.x 运行时，在 package.json 中指定：

"engines": {
  "node": "18.x"
}

5.3 Monorepo 项目部署

假设项目结构如下：

.
├── packages
│   ├── app
│   └── app-dep1
├── package.json
└── pnpm-workspace.yaml

部署步骤：

1. 在 Vercel 平台配置 Root Directory 为 packages/app
2. 在 package.json 中指定 Node.js 版本：

"engines": {
  "node": "18.x"
}

3. 在 packages/app/package.json 中添加：

{
  "scripts": {
    "build:packages": "pnpm --filter 'app^...' run build",
    "deploy": "pnpm run build:packages && modern deploy",
  }
}

4. 创建 packages/app/vercel.json：

{
  "buildCommand": "npm run deploy",
  "outputDirectory": ".vercel/output"
}

六、部署最佳实践

1. 环境变量管理：敏感信息应通过平台提供的环境变量功能配置
2. CDN 配置：静态资源建议配置 CDN 加速
3. 监控与日志：部署后配置适当的监控和日志收集
4. 回滚策略：制定部署失败时的回滚方案

通过本文的指导，您应该能够将 Modern.js 项目成功部署到各种环境中。根据项目需求选择合适的部署方式，并遵循最佳实践，可以确保应用的稳定运行和高效性能。