VuePress部署到云服务器ECS完整实操：从Markdown到公网访问

7天实践训练营进阶路线的Day1任务卡上写着四个字搭建VuePress。如果你也跟我一样第一次看到这个任务时先入为主地认为“这不过是个前端脚手架跑起来就行”那我劝你先沉住气——这个任务的真正重点其实不在VuePress本身而在于把一套静态站点从本地一直送到云服务器ECS上公网可访问。这篇记录就把我完整走通的流程、改过的配置和踩过的坑原样整理出来给同样在做训练营或者想用VuePress建站的朋友作个参照。先说结论Day1的完整链路是“本地写 Markdown → VuePress 构建静态页面 → Nginx 托管在 ECS → 用户通过公网IP/域名访问”。这个链路不算长但每一环都有新手容易卡住的细节尤其是安全组、Node 版本、路由刷新这几关。接下来按实操顺序展开。1. Day1任务到底在做什么1.1 先给新手交个底如果你刚接触这些名词我先把它们翻译成人话。云服务器ECS就是一台放在机房里、7x24小时开着的Linux电脑。你通过SSH远程连接它在上面装软件、部署网站别人就能通过公网IP访问到你的内容。VuePress是一个以Markdown为写作语言、基于Vue框架的静态站点生成器。你写几篇.md文件它帮你生成一套完整的HTML、CSS、JavaScript文件这些文件不需要数据库、不需要后端服务任意一台能托管静态文件的服务器都能跑起来。所以Day1的实质就是把VuePress生成的静态文件放到ECS上再用Nginx这个高性能Web服务器把文件发布出去。整个过程不涉及复杂后端逻辑但涉及Linux基础操作、环境变量、端口监听、文件权限等一堆服务器运维的基础技能。这也是训练营把它放在进阶路线第一天的原因——先喂给你一条完整的“建站链路”后面几天再在链路上叠加自动化、监控、优化等技能你才有坐标系。1.2 为什么选VuePress而不是WordPress或Hexo训练营选VuePress我觉得有几个很实在的理由。拿它和另外两个常见方案对比一下对比项VuePressHexoWordPress技术栈Node.js VueNode.jsPHP MySQL渲染方式构建时静态生成构建时静态生成请求时动态渲染内容写作MarkdownMarkdown后台富文本编辑器上手门槛中等偏低低PHP环境配置较繁琐部署运维单进程静态托管单进程静态托管需要PHP-FPM MySQL守护适合场景技术文档、博客、组件库文档个人博客内容站、商城、复杂站点对进阶训练营来说VuePress的优势是“链路短但技能点密集”。短是指它没有数据库依赖部署时只用管好静态文件即可密集是指配置路由、主题、构建脚本的过程能帮你熟悉现代前端工程的常见概念。而WordPress虽然功能强大却把大量复杂度转移到了PHP和数据库维护上对只想快速验证“服务器部署能力”的Day1来说明显偏重了。另外VuePress 2已经基于Vite构建本地开发冷启动和热更新都很快写文档的体验很顺。构建产物是纯静态文件交给Nginx托管后响应速度非常快也不用担心PHP运行时漏洞这类问题。对新手而言排障范围越小越容易建立信心。2. 整体方案设计与环境准备2.1 先想清楚架构再动手装软件动手之前我建议你先在纸上画一条访问链路。我自己习惯这么理解用户在浏览器输入http://服务器IP→ 请求到达云厂商机房 → 安全组规则放行80端口 → 系统防火墙放行 → Nginx监听80端口 → Nginx根据配置找到磁盘上的静态文件 → 返回首页HTML → 浏览器加载页面资源。这条链路里的每个环节都对应一个你可能踩坑的位置。后面排查问题时就是沿着这条链路一层一层倒推。所以不要急着敲命令先把链路记在脑子里后面遇到“为什么打不开”的问题你就知道至少有几个排查点而不是对着屏幕干瞪眼。为什么用Nginx而不是Apache或Caddy从Day1的角度看Nginx对静态文件的处理效率极高配置语法直观而且互联网上存量教程最多遇到问题搜解决方案基本都有现成答案。Apache也不差但配置段相对多新手容易绕晕。Caddy配置更简洁、自动管理HTTPS证书但训练营技能点更偏通用型Nginx掌握的迁移性更好。一句话选择Nginx是为了“少踩坑 通用性强”。2.2 服务器选型和安全组放行Day1阶段对服务器配置要求不高。我用的是一台2核2G内存、系统为Ubuntu 22.04 LTS的ECS实例。为什么用Ubuntu主要原因是apt包管理工具在国内镜像多、软件版本新、社区资料丰富。CentOS Stream虽然也能用但如果你后续想用新版Node.js在Ubuntu上通过nvm安装会顺手很多。买好服务器后第一件事不是装环境而是去云厂商控制台查看安全组规则。很多新手在这里就卡住了服务器里明明把Nginx装好了、服务也启动了但浏览器就是打不开多半是安全组没放行端口。Day1至少需要放行三个端口端口用途建议规则22SSH远程连接仅对可信IP放行或保持默认80HTTP访问网站对所有来源放行443HTTPS访问网站对所有来源放行安全组是云平台层面的网络访问控制相当于机房门口的保安Linux系统里还有一层防火墙相当于楼层门禁。两层都要放行才能访问通。Ubuntu系统默认一般没开ufw但如果你之前手动开过要记得执行sudo ufw allow 80/tcp和sudo ufw allow 443/tcp。登录方式建议用SSH客户端连接终端或各类SSH工具都行。我习惯直接用终端命令简洁还能顺带练习Linux操作。连接命令是ssh root你的公网IP连接成功后先做基础初始化。我个人习惯按这个顺序来避免后面权限混乱apt update apt upgrade -y adduser deploy usermod -aG sudo deploy su - deploy新用户deploy用来部署项目避免所有操作都压在root上。虽然Day1赶进度时有人嫌建用户麻烦但后续几天训练营任务要反复发布、调试用普通用户操作能少很多权限误操作的问题。3. 搭建VuePress的完整实操流程3.1 安装Node.js环境版本认准LTSVuePress 2要求Node.js版本不低于18。这里有个常见的坑用Ubuntu自带的apt直接安装nodejs装到的版本往往是v12或v14远远不够。所以推荐用nvm来安装和管理Node版本它可以按项目随时切换版本也能避免后面npm全局写入权限问题。安装nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc然后安装Node 20 LTS版本nvm install 20 nvm use 20 node -v npm -v我这里选20而不是最新版本考虑的是LTS版本的稳定性。VuePress的依赖生态比较大用LTS版本遇到兼容性问题的概率最低。如果你后续要在同一台服务器上跑多个Node项目nvm的版本管理能力会非常有用这是直接apt安装nodejs给不了的。npm在国内安装依赖时偶尔会比较慢可以设置镜像源提升速度npm config set registry https://registry.npmmirror.com设完后npm install的速度会明显改善。这一点在服务器上尤其重要因为服务器网络环境有时候比本地更不稳定。3.2 初始化VuePress项目移到部署目录我习惯把网站项目放在/var/www/下面跟系统文件分开sudo mkdir -p /var/www/vuepress-site sudo chown -R deploy:deploy /var/www/vuepress-site cd /var/www/vuepress-site然后初始化项目npm init -y npm install -D vuepressnext vuepress/client mkdir -p docs/.vuepress这里装的是VuePress 2所以用的是nexttag。注意不要直接npm install -g vuepressVuePress推荐局部安装方便每个项目锁定自己的版本。创建文档首页docs/README.md# 我的云服务器ECS实践笔记 这是我在7天实践训练营Day1搭建的VuePress站点。 - 支持Markdown写作 - 支持代码高亮 - 部署在ECS上公网可访问再创建配置文件docs/.vuepress/config.jsmodule.exports { lang: zh-CN, title: 云服务器ECS实践笔记, description: VuePress站点搭建与部署练习, themeConfig: { navbar: [ { text: 首页, link: / }, { text: 关于, link: /about.html }, ], }, }修改package.json加上两个脚本命令{ scripts: { docs:dev: vuepress dev docs, docs:build: vuepress build docs } }这里有个经验VuePress 1和VuePress 2的构建目录不一样。前者默认输出到docs/.vuepress/dist后者也一样但一些主题或插件会改这个路径。Day1用默认路径就够后面折腾主题时再关注这个配置项。3.3 本地构建确认产物生成成功VuePress的工作流是先写Markdown再构建成静态HTML。先用开发模式预览一下效果npm run docs:dev终端会输出一个本地预览地址一般是http://localhost:8080。用浏览器确认页面正常后按CtrlC停掉开发服务然后执行正式构建npm run docs:build构建完成后检查产物是否生成ls -la docs/.vuepress/dist看到index.html和若干资源目录就说明构建成功了。这个dist目录就是后面Nginx要托管的根目录。这里我建议两种部署方式选一种一是在本地构建好之后把dist整个传到服务器二是在服务器上直接拉代码、装依赖、构建。Day1阶段项目很小两种都行。但考虑到训练营后面几天的任务会涉及自动化发布我建议从Day1开始就养成“代码在服务器上构建”的习惯这样后续在服务器上直接操作更顺手。3.4 Nginx托管核心配置与路由陷阱安装Nginxsudo apt install nginx -y sudo systemctl enable nginx sudo systemctl start nginx装完后先在浏览器里访问一下服务器公网IP如果能到Nginx默认欢迎页说明Nginx、安全组、防火墙这一侧都通了。这其实是个很好的“分段验证”技巧把服务器通路和项目部署拆成两段来检查避免一出问题就搞不清是哪边的故障。接下来为VuePress站点建一个单独的配置文件sudo vim /etc/nginx/conf.d/vuepress.conf写入如下配置server { listen 80; server_name example.com; # 换成你的域名或公网IP root /var/www/vuepress-site/docs/.vuepress/dist; index index.html; location / { try_files $uri $uri/ /index.html; } }然后测试配置并重载sudo nginx -t sudo systemctl reload nginx这里最关键的配置是try_files $uri $uri/ /index.html;。VuePress默认使用History路由模式这种模式下路径是“真实路径”的表现形式比如https://example.com/about.html。Nginx在收到/about.html请求时会去找磁盘上是否存在这个文件找到了就返回。如果直接访问/about/这类没有实际HTML文件的路径Nginx就会返回404所以需要通过try_files把找不到的URL回退到index.html由前端路由接手渲染。如果你在配置里漏了这行表现是首页能打开点导航跳转也没问题但一旦刷新二级页面浏览器就白屏或报404。这个坑几乎每个用VuePress的人都会遇到一次记得排查顺序是先看Nginx配置再看代码。还要注意有些云厂商镜像默认启用了Nginx的默认站点/etc/nginx/sites-enabled/default它监听了80端口。如果发现自己的配置没生效先执行sudo rm /etc/nginx/sites-enabled/default再重载Nginx释放80端口给我们的站点。3.5 域名解析与HTTPSDay1阶段值得一并通关如果手头有域名强烈建议在Day1就把域名解析配好。去域名服务商控制台添加一条A记录主机记录填或www记录值填服务器公网IP。DNS生效一般需要几分钟到几小时不等可以用ping 你的域名验证是否解析到了自己的服务器IP。解析生效后把Nginx配置里的server_name改成域名然后重载即可通过域名访问。HTTPS在Day1可以直接配好因为它涉及不少服务器知识的整合早配早受益。先申请一个免费SSL证书现在主流云厂商都提供免费的证书服务拿到证书文件和密钥文件后Nginx配置增加443端口监听server { listen 443 ssl http2; server_name example.com; ssl_certificate /etc/ssl/example.com.pem; ssl_certificate_key /etc/ssl/example.com.key; root /var/www/vuepress-site/docs/.vuepress/dist; index index.html; location / { try_files $uri $uri/ /index.html; } } server { listen 80; server_name example.com; return 301 https://$host$request_uri; }改了配置后记得sudo nginx -t测试再重载。完成后访问域名就会自动跳到HTTPS。这一步做完后面训练营里做接口联调、跨域测试、PWA等任务时就不会被“混合内容”之类的问题干扰省心很多。4. 踩坑记录常见问题与排查思路4.1 公网IP打不开页面这是最经典的问题表现是服务器本地curl http://localhost能返回HTML但浏览器访问公网IP一直转圈或超时。问题几乎都出在网络链路上按顺序排查curl http://localhost ss -tlnp | grep 80 sudo systemctl status nginx sudo ufw statuscurl localhost验证Nginx进程ss看80端口是否处于监听状态systemctl status看服务是否异常退出ufw status看系统防火墙是否拦截。如果这些都没问题马上去云厂商控制台看安全组规则确认80端口是否放行。公有云的安全组和系统防火墙是两层独立的控制任何一个没放行都进不来。顺带说一句有一些云厂商的主机有“网络ACL”之类的额外网络控制层如果你在安全组和ufw都放了行还是不通去控制台里翻翻有没有其他网络策略这个问题极少见但遇到一次就够折腾半小时。4.2 npm安装慢或超时服务器网络环境有时候不如本地稳定装VuePress依赖时经常卡在某个包上。解决办法就是前面提到的配置镜像源。如果大项目依赖特别多还可以用npm install --registryhttps://registry.npmmirror.com临时指定源不用改全局配置。另外一个常见问题是Node版本过低导致安装过程中出现语法错误。装依赖之前建议先用node -v确认版本大于等于18如果不够用nvm升级到20。不要偷懒用apt直接升级apt默认源里的Node版本常年偏旧。4.3 页面样式全丢或资源404如果你把站点部署在域名根路径config.js里设置base: /即可。但如果你部署在类似http://ip/blog/的子路径下就必须设置base: /blog/否则构建出的HTML里引用的CSS和JS路径都从根目录找自然全部404。这个问题的特点是HTML能打开但页面没有样式控制台一堆资源加载失败。排查时先按F12看网络面板确认静态资源的请求路径再有针对性地调整base配置。4.4 构建时内存不足或进程被杀2G内存的服务器构建VuePress时偶尔会遇到进程被OOM Killer干掉的情况特别是安装了较多插件之后。一个简单有效的办法是加Swap文件给服务器扩展虚拟内存sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile把Swap加到2G后构建基本不会再被内存问题打断。这个操作本身也是服务器运维的常见技能Day1阶段练一次不亏。需要注意的是这只是临时缓解如果项目持续变大还是得考虑升级实例配置或者优化构建方案。4.5 常见问题速查表症状可能原因解决动作80端口公网访问不通安全组未放行控制台放行80/44380端口公网访问不通系统防火墙拦截sudo ufw allow 80/tcp80端口公网访问不通Nginx默认站点占用删除sites-enabled/default网站能开但刷新404缺少try_files配置/index.html回退样式全丢base路径配置错误子路径部署时设置basenpm install卡住镜像源慢配置国内npm镜像构建进程被杀内存不足增加Swap或升级配置域名访问不了IP可以DNS未生效或未解析ping域名并检查A记录5. 后续扩展Day2往后可以怎么玩5.1 部署脚本化向自动化发布迈进Day1结束后如果每次改文章都要手动SSH登录、进目录、拉代码、构建、重载Nginx很快就会烦。我Day2做的事就是把部署过程写成一个脚本#!/bin/bash cd /var/www/vuepress-site git pull origin main npm run docs:build sudo systemctl reload nginx脚本内容很简单但它标志着“手动部署”到“半自动化部署”的转变。之后再用Git的Webhook触发这个脚本就能实现本地推送代码服务器自动更新页面的效果。这也正好衔接到训练营后面关于自动化、DevOps的进阶内容。5.2 功能和体验增强方向VuePress站点的可扩展性很强Day1基础打牢后后面可以叠加这些能力评论系统接入第三方评论服务或自建轻量评论后端让博客具备互动能力。统计与分析部署一款访问统计工具了解站点流量和访客来源。主题定制默认主题满足基础文档需求进阶可以改布局、自定义Vue组件、添加快捷键等功能。SEO优化利用VuePress自带的SEO能力给每篇文章补全描述、关键词等元信息。PWA离线支持接入PWA插件让站点具备离线访问和安装到桌面的能力。这些扩展对服务器本身的压力都不大2C2G完全够用。逐项添加的过程本身就是训练营进阶路线想让你体验的“在一个真实项目上持续迭代”的节奏。最后说点个人体会。第一次把VuePress完整部署到ECS上时我最大的收获不是“学会了VuePress”而是对一台云服务器的结构从黑盒变成了白盒安全组是门槛系统防火墙是门禁Nginx是前台静态文件是货架。以前看到“部署”两个字总觉得很虚等自己一步步把链路打通后才发现它无非是把文件放到正确的位置再让正确的进程监听正确的端口。操作上再分享一个小技巧Day1阶段就把域名和HTTPS配好能让你后面几天省很多事。后续的自动化发布、跨域联调、PWA等功能都依赖一个相对正式的站点环境早点把基础铺好后面的每个任务都能直接站在这个地基上继续盖楼。