AI提示词+VitePress:半小时搭建Node.js学习官网
去年年中我想搭一个 Node.js 学习资料站,当时脑子里有个很具体的诉求:内容要能持续更新、页面打开要快、最好不用花几周时间从零手写页面。试过几个方案之后,我摸到了一条非常顺的路径——用一条结构完整的提示词让 AI 生成整个 VitePress 官网骨架,再推送到 GitHub 接上托管平台的自动部署,从本地跑通到线上发布,前后不到半小时。这篇文章就把整个过程拆开讲清楚,包括怎么设计提示词、Node.js 环境怎么选版本、官网内容模块怎么排、发布走哪条路最省事,以及我实际部署时踩过的几个坑。
先泼一盆冷水:题目里说的“一句话生成”,不是真的只丢十个字过去就能拿到成品。如果只写“帮我做一个 Node.js 学习官网”,AI 大概率会给你一大坨结构混乱的代码,目录乱、内容空,改起来比从零写还痛苦。真正靠谱的做法,是把你的技术栈、目录结构、内容范围、构建方式这些关键决策全部压缩进一段提示词里,让 AI 帮你一次性把骨架搭对。这本身就是一个很典型的需求梳理过程,提示词写得越清晰,后边返工越少。
1. 为什么学习资料站我选 VitePress,而不是手写 HTML 或 WordPress
判断用哪个工具之前,先想清楚你的站点到底是什么形态。Node.js 学习官网这类站点,内容主体是安装教程、语法笔记、框架用法、部署实操这类结构化文档,更新频率高,而且需要侧边栏导航、全文搜索、代码高亮这些配套能力。如果手写 HTML,等于每加一篇文章都要重复处理导航和样式,维护成本直接失控;用 WordPress,又显得笨重,服务器资源、数据库、安全更新全要自己操心。
我当时实际比过三条路线:
| 方案 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|
| 手写 HTML/CSS/JS | 完全可控,没有框架约束 | 内容一多就是维护灾难,导航、搜索要自己写 | 三五个静态页面 |
| Docusaurus | 组件生态好,适合大型产品文档 | 配置相对复杂,主题定制链路较长 | 产品级文档站 |
| VitePress | 轻量、构建快、Markdown 直接成站 | 插件生态不如 Docusaurus 丰富 | 个人技术站、学习资料站、中小型文档 |
VitePress 最打动我的几个点:第一,它基于 Vite,本地开发启动速度极快,几百篇文章的站也能做到瞬间热更新;第二,所有内容都用 Markdown 写,你不用关心页面结构,只要专注写内容;第三,默认主题自带了左侧导航、右侧目录、搜索框、明暗切换,这些功能如果手写,够你折腾两个周末;第四,构建产物是纯静态 HTML,丢到任何静态托管平台上都能跑,部署思路非常直接。
还有一个很实际的理由:Node.js 教程站的文章经常要贴代码示例。VitePress 内置了 Shiki 代码高亮,直接写代码块就能出效果,还能自动显示行号、高亮某一行,这些功能拿来写语法教学特别顺手。另外它对 Markdown 的扩展语法支持得不错,笔记里想塞个提示框、折叠块、表格,都不用额外装插件。
2. 提示词怎么设计:一次让 AI 把官网骨架搭对
2.1 我最终用的提示词模板
核心思路不是让 AI“写代码”,而是让 AI“按我的要求搭一个可直接运行的项目”。我把技术栈、目录结构、主题配置、内容占位全部写进提示词。如果你也想复现,可以直接复制下面这段,按需改一下站点名和目录结构:
我有一段类似这样的提示词(这里简化了一下结构,实际使用可以更细):
请帮我创建一个基于 VitePress 的 Node.js 学习官网项目。要求:
- 使用 pnpm 作为包管理器,package.json 的 scripts 包含 docs:dev、docs:build、docs:preview。
- 根目录结构必须包含 docs/.vitepress/config.mjs、docs/index.md、docs/guide/install.md、docs/guide/npm.md、docs/guide/http.md、docs/guide/deploy.md,以及 docs/.vuepress(如果不需要可以去掉)——注意这里我最后实际用的是 docs/.vitepress 目录。
- 侧边栏按模块划分,包括快速上手、核心概念、常用模块、工程化、部署上线五个分组。
- 首页要包含 Hero 区块,主标题是“Node.js 学习指南”,副标题是“从安装到部署的一站式教程”,并给出两个按钮:快速开始、GitHub 仓库。
- 每个指南文章的 frontmatter 都要配置 title 和 description,方便后续 SEO。
- 整体视觉风格简洁偏深色,导航栏右侧要有 GitHub 链接。
- 不要使用外部图片资源,图标用文字或 emoji 占位即可(如果用 emoji 后续替换成 @iconify-json 图标也行)。
这么写的好处是:AI 知道这不是在写演示片段,而是在生成一个真实可用的项目。目录一旦固定下来,后续加文章只要往对应目录扔 Markdown 就行,导航结构不会被带偏。
2.2 AI 生成后的目录长什么样
一次生成完之后,我检查了一下目录结构,基本符合预期:
这里要特别注意 .gitignore——部署的时候见过好几个人把 node_modules 推到 GitHub 上,仓库瞬间膨胀到几百 MB,托管平台每次构建都要重新安装依赖,不停报错。所以在让 AI 生成项目时,明确要求包含 .gitignore 且忽略 node_modules、.DS_Store、dist 这些目录。
config.mjs 里最重要的一段是侧边栏配置。AI 生成的初始版本往往分组太宽泛,我会手动调整成下面这种贴近实际学习路径的结构:
这样排布的学习路径是从初学者视角设计的,先把环境跑通,再来理解核心机制,最后落到工程化部署,文章之间是有递进关系的。AI 生成的侧边栏通常只是平铺所有页面,没有教学逻辑,所以这个手调步骤值得做。
3. 本地环境准备:Node.js 版本选型与安装细节
3.1 版本怎么选:LTS 优先,别动不动追新
VitePress 对 Node 版本有硬性要求,低于 18 直接跑不起来。所以在搭官网之前,先要把本机 Node 环境理顺。这里我强烈建议用版本管理器,而不是直接去官网下载一个安装包装到系统里——后者虽然简单,但日后切换项目版本时非常痛苦。
- Windows 用户:装
nvm-windows,注意不要和已安装的 Node 环境冲突,装之前最好把系统原有的 Node 卸掉。 - macOS / Linux 用户:直接用
nvm,一条安装命令搞定。 - 如果不想用 nvm,也可以用
fnm(用 Rust 写的,速度更快),但生态熟悉度不如 nvm。
装好之后,安装 LTS 版本。当前时期比较稳的是 Node.js 18.20.x 或 20.x 系列。我实际用的是 18.20.4 LTS——这个版本号也是热门搜索里常出现的版本,说明确实是大多数人在用的稳定选择。官方下载页会把 LTS 和 Current 并列展示,记住一条原则:除非你确实需要测试新特性、或者用到了只支持新版 Node 的工具链,否则永远选 LTS。VitePress 这类文档站对运行环境要求不高,LTS 完全够用,还避开了新版本刚发布时生态兼容性的各种问题。
3.2 安装后的验证与提速配置
安装完成之后,终端里依次跑这几个命令:
node -v 至少要输出 v18.x.x 以上。npm -v 会输出 npm 版本。确认没问题后,我建议立刻做两件事,不然 npm install 能让你等到怀疑人生。
第一件事,把 npm 默认源切到国内镜像:
第二件事,装一个 pnpm。VitePress 官方文档推荐 npm 和 pnpm 都行,但实测下来 pnpm 的安装速度和磁盘占用明显更优,特别是后续依赖多了以后差距更大:
然后是项目启动。如果你是照前面的提示词让 AI 生成的项目,进到目录后:
正常情况下,终端会输出一个本地访问地址,通常是 http://localhost:5173,浏览器打开就能看到前台首页。这里有一个很多人第一次跑会踩的问题:端口被占用。VitePress 默认用 5173,被占的话会向后顺延到 5174,终端里会明确提示实际地址,不要眼睛只盯着第一行输出。
4. 学习官网的内容模块:不是堆文章,是排学习路径
4.1 从环境到部署的内容主线
一个能持续留住访客的学习官网,内容组织必须有主线。我当时定的是五个模块:快速上手、核心语法、核心概念、常用内置模块、工程化与部署。这五块正好对应一个新手从零到能独立部署 Node.js 服务的完整路径。
快速上手放两篇就够:安装与版本选择、npm 基础与镜像配置。这两篇文章解决的是“环境能不能跑起来”的问题。很多教程站一上来就讲语法,结果读者安装那一步就被劝退了。所以我会在 install.md 里不厌其烦地把 Windows、macOS、Linux 三种系统的安装步骤分开写,并把常见的 node: command not found、npm 镜像访问超时这类问题前置列出。你别觉得这些内容基础,搜索后台数据告诉我,访问量最高的往往就是这类“入门中的入门”文章。
接着是核心语法和概念,重点是模块机制和事件循环。CommonJS 与 ESM 的模块差异、事件循环的六个阶段,这两块是 Node.js 初学者最容易混的地方,也是面试经常考的部分。每篇文章开头我都会放一个“目标”小框,告诉读者这篇学完能做什么。
核心概念与内置模块这两块可以交叉着排——比如讲 HTTP 模块时,顺带说清楚 Node.js 内置的 http 模块和 Express 框架的关系;讲文件系统时,把 fs.promises API 和同步/异步的选择逻辑说透。最终落到工程化和部署:PM2 怎么守护进程、Nginx 反向代理怎么配、怎么部署到 Vercel 或一台 CentOS 7.9 服务器上。
4.2 Markdown 写作与代码高亮的细节
VitePress 的 Markdown 语法几乎兼容 GitHub Flavored Markdown,所以贴 GitHub 的 README 进来基本不用改。唯一要注意的是代码块的标注,语言写错了会导致高亮失效:
5. 秒发布上线的两条路线:托管平台与自有服务器
5.1 路线一:GitHub + Vercel,推荐首选
标题里的“秒发布上线”,我实际走的是这条路。Vercel 对 VitePress 的支持几乎是零配置的——项目推送到 GitHub 之后,在 Vercel 里导入仓库,它会自动识别 VitePress 项目,Framework Preset 直接选 VitePress,构建命令和输出目录通常都不用改。
流程分几步:
- 在 GitHub 上新建一个仓库,把本地项目推上去。
-
打开 Vercel 官网,用 GitHub 账号登录,点 Add New Project,选中刚推的仓库。
-
Framework Preset 选 VitePress。如果 Vercel 没识别出来,手动检查两项:Build Command 填
pnpm run docs:build,Output Directory 填docs/.vitepress/dist。 -
点击 Deploy,等十几秒到几十秒,就能拿到一个
*.vercel.app的线上地址。
这里要解释一下为什么构建输出目录是这样:VitePress 默认把构建产物输出到项目根目录的 docs/.vitepress/dist 下,而不是像 VuePress 那样直接输出到 dist。这点很多人配置错了,导致部署上去访问全是 404。
线上地址生效之后,如果想绑定自己的域名,在 Vercel 项目设置里的 Domains 里填上域名,按提示去 DNS 服务商加一条 CNAME 或 A 记录,一般几分钟就能生效,而且 Vercel 自动托管 HTTPS 证书,不用自己手动配 SSL。这一步对于“秒发布”的体验非常关键,因为 HTTPS 证书现在已经是所有网站的默认要求了。
5.2 路线二:CentOS 7.9 服务器手动部署
如果你已经有了一台 CentOS 7.9 的服务器,而且希望把站点放在自己的域名和服务器环境里,也可以走手动部署路线。这条路径稍微多一点步骤,好处是服务器所有权完全在自己手里。这里我按实操顺序写,同时补充几个容易出问题的点。
先在服务器上装 Node.js。CentOS 7.9 自带的源里的 Node 版本很老,直接 yum install nodejs 装出来的可能是 v10 甚至更老,跑 VitePress 必挂。推荐用 NodeSource 源或者二进制包安装,更简单的是直接用 nvm:
然后从 GitHub 拉代码,构建:
构建完成后,docs/.vitepress/dist 就是完整的静态文件。接下来用 Nginx 托管:
然后重载 Nginx:
几个容易卡住的地方我当时都遇到过:第一,SELinux 没关或没放行 Nginx 对目录的访问权限,导致静态文件 403;第二,server_name 和实际域名不一致时,访问会跳到默认站点;第三,如果配了 HTTPS 但证书链没配全,浏览器会报不信任。后两条排查起来都不难,一般就是看 Nginx 错误日志和 nginx -t 的输出就能定位。
相比 Vercel,这种方式的部署时间会长一些,因为要手动执行构建和 Nginx 配置。但如果你是做企业内网项目,或者要求站点必须部署在自己的网络环境里,那走这条路线反而是刚需。
5.3 表格对比一下这两条路线
| 对比维度 | Vercel 托管 | CentOS 7.9 自建 |
|---|---|---|
| 部署时间 | Git 推送后自动构建,约 1 分钟内 | 手动构建 + Nginx 配置,5 到 10 分钟 |
| 主要成本 | 免费版即可满足个人站需求 | 需要服务器的维护成本 |
| HTTPS 证书 | 自动申请和续期 | 需要自行用 certbot 或手动配置 |
| 更新和维护 | 改代码推 GitHub 即生效,几乎零运维 | 需要登录服务器拉代码再构建 |
| 适用场景 | 个人博客、学习资料站、快速原型 | 政企项目、内网环境、要求自控的场景 |
两条路线可以同时走。我自己的做法是:默认用 Vercel 托管对外访问,同时在服务器上留了一份构建产物作为备份入口。这样不管哪条链路出问题,站点都不至于完全不可用。
6. 上线之后必须处理的几个细节:构建失败排查与 SEO 配置
6.1 我遇到过的一次构建失败排查链路
第一次用 Vercel 部署的时候,构建直接失败了,日志里报了一行 Cannot find module '@vitejs/plugin-vue'。乍一看像依赖没装全,但我本地明明跑得好好的。后来一步步排查才发现问题根源:我在 Vercel 项目设置里把 Node 版本默认到了 16.x,而 VitePress 的依赖链里有部分包要求 Node >= 18。这个坑很容易踩,因为本地是 18.20.4 跑通的,线上环境默认版本却不一致。
排查路径是:
- 先看构建日志的第一条错误和最后一条错误,确认是模块解析失败还是 Node 版本不支持。
- 如果报模块找不到,先
pnpm install看本地能不能复现,能复现就是 lockfile 的问题; - 本地无法复现,重点检查托管平台的环境配置,Vercel 里项目设置的 Node Version。
- 最终我在 Vercel 项目 Settings 里把 Node Version 切到 20.x,重新部署,构建通过。
这个排查过程其实适用于几乎所有静态站构建问题:本地能跑、线上不能跑,十有八九是环境差异的锅,优先检查 Node 版本与包管理器版本。另一个相关的问题是 lockfile 不一致,本地用 pnpm 生成 pnpm-lock.yaml,如果托管平台默认用的是 npm,有概率出现依赖解析不一致。解决方式是,项目根目录只保留一个包管理器的 lockfile,并在 package.json 里加 packageManager 字段声明:
这样 Vercel 这类平台会优先使用 pnpm 来安装依赖,避免 npm 和 pnpm 混合带来的各种诡异问题。
6.2 base 路径配置:决定你的静态资源加载位置
VitePress 的 base 配置决定了构建后静态资源的路径前缀。如果你部署在 Vercel、Netlify、或者自己域名的根路径下,base 保持默认的 '/' 即可,不用改。但如果你部署在 GitHub Pages 的二级路径下,比如 https://username.github.io/repo-name/,就一定要在 config.mjs 里设置:
这个配置在我实际部署时非常关键。第一次用另一个平台部署时忘了加,结果所有 CSS 和 JS 都 404,页面裸 HTML 一堆,看起来非常尴尬。判断方法也简单,打开线上 Page Source,看 <link> 引用的路径开头是 / 还是 /repo-name/,不一致就是 base 配错了。
6.3 SEO 与站点元信息配置
网站上线只是开始,更长久的工作是让搜索引擎能完整收录。VitePress 默认主题已经做了不少基础 SEO 工作,但还是建议在 config.mjs 里显式配置站点信息:
配置里的 sitemap 可以自动生成 sitemap.xml 文件,把它提交到搜索引擎的站长后台,能加快收录速度。还有一个可能被忽略的点:每篇文章的正文里尽量多布置几个到其他文章的内链,这不仅能引导读者延续学习路径,对搜索排名也有好处。
6.4 更新一次内容可以直接推 GitHub
所有内容就位后,“秒发布上线”的长尾体验其实来自持续更新的顺畅感。我现在的做法:新建文章就在 docs/guide 下放一个 Markdown 文件,写完 git add、git commit、git push,Vercel 自动触发构建,一般几十秒新版就上线了。整个过程不需要碰服务器,不需要 SSH 登录,也不需要手动执行任何构建命令。对比之前用 WordPress 时的体验,维护感完全是两个世界。
最后分享一个我个人的使用体会:像这类学习官网,最怕的不是内容少,而是内容结构混乱。VitePress 天然适合结构化文档,只要你维护好侧边栏分组,就不用担心站点失控。而“一句话生成”的本质,其实是把需求想清楚再交给 AI——你先知道自己要什么,AI 才能真正帮上忙。官网搭好之后,后续的内容更新应该尽量走一个固定模板,保持格式一致,这样既省时间,读者看着也舒服。