如何在Next.js中部署Hocuspocus协作编辑WebSocket服务器？

方案一：将Hocuspocus服务器集成到Next.js项目中 #

Next.js的无服务器架构并非完全无法运行WebSocket服务，可通过以下两种方式实现集成：

方法1：自定义Node.js服务器 #

通过自定义服务器让Next.js和Hocuspocus共享同一个HTTP服务进程：

1. 在项目根目录创建server.js：

const { createServer } = require('http');
const { parse } = require('url');
const next = require('next');
const { Hocuspocus } = require('@hocuspocus/server');

const dev = process.env.NODE_ENV !== 'production';
const app = next({ dev });
const handle = app.getRequestHandler();

// 初始化Hocuspocus，不指定固定端口避免冲突
const hocuspocusServer = new Hocuspocus({ port: 0 });

app.prepare().then(async () => {
  const httpServer = createServer((req, res) => {
    const parsedUrl = parse(req.url, true);
    handle(req, res, parsedUrl);
  });

  // 将Hocuspocus挂载到当前HTTP服务器
  await hocuspocusServer.attach(httpServer);

  httpServer.listen(process.env.PORT || 3000, () => {
    console.log('> Ready on http://localhost:3000');
  });
});

2. 修改package.json启动脚本：

"scripts": {
  "dev": "node server.js",
  "build": "next build",
  "start": "NODE_ENV=production node server.js"
}

3. DigitalOcean部署时，选择Droplet虚拟机或App Platform容器模式，不要用无服务器静态站点部署——这类环境无法维持Node.js进程持续运行。

方法2：Edge API Routes（适配无服务器环境） #

利用Next.js Edge Runtime处理WebSocket连接，适合DigitalOcean App Platform等无服务器场景：

1. 创建app/api/hocuspocus/route.js：

import { Hocuspocus } from '@hocuspocus/server';

export const runtime = 'edge';

export async function GET(req) {
  // 仅处理WebSocket升级请求
  if (!req.headers.get('upgrade')?.includes('websocket')) {
    return new Response('Not Found', { status: 404 });
  }

  const { socket, response } = await req.upgrade();
  const server = new Hocuspocus({
    // 按需配置存储、认证等扩展
  });

  server.handleConnection(socket);
  return response;
}

注意：需确认DigitalOcean App Platform当前支持Edge Runtime的WebSocket升级能力，部分场景可能存在限制。

方案二：独立部署Hocuspocus服务器（无需静态IP） #

无需静态IP，只需给服务器配置可访问的域名即可：

步骤1：部署独立服务 #

1. 创建单独的Node.js项目，写入Hocuspocus配置：

import { Hocuspocus } from "@hocuspocus/server";
import { SQLite } from '@hocuspocus/extension-sqlite';

const server = new Hocuspocus({
  port: 1234,
  extensions: [
    new SQLite({ database: './database.sqlite' })
  ]
});

server.listen();

2. 在DigitalOcean选择Droplet或App Platform部署该项目，部署后会自动分配公网IP或生成临时域名（如your-hocuspocus-app.ondigitalocean.app）。

步骤2：配置反向代理（可选，用于自定义域名+SSL） #

若要绑定自定义域名，用Nginx做反向代理：

server {
    listen 443 ssl;
    server_name your-custom-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:1234;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

步骤3：客户端连接配置 #

在Next.js客户端代码中修改Hocuspocus连接地址：

import { HocuspocusProvider } from '@hocuspocus/react';
import { EditorContent, useEditor } from '@tiptap/react';

export default function Editor() {
  const editor = useEditor({ /* Tiptap配置 */ });

  return (
    <HocuspocusProvider
      url="wss://your-hocuspocus-server-domain.com"
      name="document-id"
      editor={editor}
    >
      <EditorContent editor={editor} />
    </HocuspocusProvider>
  );
}

生产环境关键注意事项 #

• DigitalOcean App Platform部署独立Hocuspocus服务时，需在项目设置的Networking中开启WebSocket支持。
• 无论哪种方案，生产环境必须使用wss://协议（配置SSL证书），避免明文传输。
• 集成自定义服务器时，务必关闭Next.js的自动静态优化，确保服务器进程稳定运行。

内容的提问来源于stack exchange，提问作者user2947684