圣堂之魂
Fumadocs 折腾记

部署到自有服务器

笔者以 Debian 13 发行版为例。


一、环境准备

1.服务器环境配置

使用 NodeSource 官方脚本安装 Node.js 20

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs

安装 pnpm

sudo npm install -g pnpm

验证:输入 node -v 显示 v20.x,pnpm -v 显示版本号。

二、打包本地文件并上传

1.打包本地文件

在本地将需要的文件打包为 .zip,通过 scp 上传到你的服务器,然后解压。

确保你的打包目录包含:

next.config.mjs
source.config.ts
tsconfig.json
package.json
pnpm-lock.yaml
postcss.config.mjs

如果您习惯使用命令行(需要安装 7ztar),可以在 PowerShell 中执行:

Compress-Archive -Path 'app','components','content','lib','public','next.config.mjs','source.config.ts','tsconfig.json','package.json','pnpm-lock.yaml','postcss.config.mjs' -DestinationPath blog.zip

注意:请仔细核对。在打包前使用 cd 指令进入对应文件夹。

2.上传到服务器

3.解压

cd /(你存放的文件夹)
unzip -o Blog.zip     # 解压到当前目录
rm Blog.zip           # 可选,删除 zip 文件

注意:若服务器没有 unzip 命令,请先安装:sudo apt install unzip -y

三、构建和部署

1. 构建文件

cd /(你存放的文件夹)
pnpm install           # 根据 package.json 重新安装,会自动下载 Linux 版二进制
pnpm build
SSH 输出 ✓ Compiled successfully 并显示路由表(无红色 error)。
如果之前从 Windows 上传,可能遇到 sharp 等二进制不兼容,必须删除 node_modules 重新执行命令 pnpm install

2. 修改端口映射

默认情况下 next start 会监听 0.0.0.0(所有网络接口),这意味着外界可以直接通过服务器的 IP:3000 端口访问你的应用,绕过了 Nginx 的反向代理,并且可能带来安全隐患。

加上 --hostname 127.0.0.1 后,Next.js 只监听本地回环地址,只能被同一台服务器上的 Nginx 访问,外部无法直接连接 3000 端口。这样可以强制所有流量都经过 Nginx,也避免了端口暴露问题。

打开项目根目录下的 package.json,找到 "scripts" 中的 "start" 一行,将其修改为:

npm pkg set scripts.start="next start --hostname 127.0.0.1"

或者使用 pnpm(效果相同):

pnpm pkg set scripts.start="next start --hostname 127.0.0.1"

验证:输入 grep start package.json 显示 "start": "next start --hostname 127.0.0.1"

3. 使用 PM2 启动(可选,推荐)

  1. 安装和开启 PM2

为了确保 Next.js 在后台持久运行,并能自动重启,我们使用 PM2 来管理进程。

若你的服务器还没安装 PM2 ,请执行 npm install -g pm2 安装。

进入项目目录并启动应用(推荐指令)

cd /(请替换为你的实际项目路径)
pm2 start pnpm --name my-website -- start

  1. 保存进程列表并设置开机自启
pm2 save                 # 保存当前运行的进程
pm2 startup              # 生成开机自启命令,按提示执行输出的那一行
  1. 验证应用是否正常运行
pm2 list 应显示 my-website 状态为 online
sudo netstat -tulnp | grep 3000 应显示 127.0.0.1:3000,且进程名为 node
curl http://127.0.0.1:3000 应返回 HTML 内容(或重定向到 /docs)。

提示:PM2 只需要启动一次。之后如果服务器重启,pm2 startup 设置的开机自启会自动恢复进程,无需再次执行 pm2 start。后续代码更新只需执行 pm2 restart my-website 即可。

4. 更新

每次更新代码或内容后,只需执行:

cd /(请替换为你的实际项目路径)
pnpm build
pm2 restart my-website

四、 配置 Nginx 反向代理

OpenReay 中创建反向代理站点,域名指向 http://127.0.0.1:3000 即可。



本页目录