安装 vagejs 并快速开始

环境要求

Node.js 22.12 或更高版本（用 node --version 查看）
npm，安装 Node.js 时自带
可选：Chrome，如果你想在本地运行 Lighthouse 审核

vagejs 可以在 macOS、Windows 和 Linux 上运行。它构建出的网站是普通文件，访客不需要任何特殊的东西。

创建新网站

terminal

npm create vagejs@latest my-site

这会创建一个 my-site 文件夹，里面有示例页面、一个布局、设置文件、给 AI 助手看的 AGENTS.md，以及 GitHub 工作流。这个文件夹必须还不存在，或者是空的。

接着它会问 Install and start the site now?（现在安装并启动网站吗？）按回车，它就会用你运行命令时所用的包管理器（npm、pnpm、yarn 或 bun）安装所有依赖。然后它会问你想用什么来搭建网站：

Build your site with:
  1. Claude Code
  2. Codex
  3. The browser editor (no coding tool needed)
  4. Just open the site

它只会列出在你电脑上找到的助手：Claude Code、Codex、Gemini CLI、VS Code（Copilot chat）和 Cursor。无论选哪一项，你的网站都会在浏览器里打开。

Claude Code、Codex 或 Gemini CLI 会直接在终端里启动，并带上第一条提示词：让助手阅读网站的 AGENTS.md，询问你的业务情况，再和你一起完成后续步骤。助手打开期间网站会一直运行，按 Ctrl+C 中断的是助手，而不是网站。如果它问你是否信任这个文件夹，选择是：这就是你刚刚创建的网站。
VS Code 会打开聊天窗口，并带上那条第一条提示词。Cursor 会打开这个文件夹，并把提示词打印出来，供你粘贴到它的聊天窗口里。
浏览器编辑器会在网站旁边打开，并为你的新网站列出一份后续步骤。

或者直接编辑 src/pages/index.md，保存后页面就会自动刷新。

当 AI 助手、脚本或 CI 运行这条命令时，它不会提问，也不会启动任何东西，而是打印出后续步骤（cd my-site、npm install、npm start），并告诉助手去阅读 AGENTS.md，和你一起完成 npx vage next-steps，向你询问真实的信息。这条命令总会执行完毕。加上 -- --yes 可以不提问直接安装并启动，加上 -- --no-install 则只创建文件。

以后要再次启动网站，在该文件夹里打开终端，运行 npm start：

terminal

cd my-site
npm start

想自己打开浏览器？npm run dev 会启动同一个服务器，但不打开浏览器，并打印出访问地址。如果浏览器显示 HTTP 431，请参阅故障排除。

你会得到什么

想看看最终效果？案例（英文）里有三个用同一个起始模板搭建的完整网站，并附有源代码。

my-site/
├── src/pages/         every .md or .mdx file is a page (a blog index is included)
├── src/layouts/       the HTML around each page
├── public/            files copied as-is (favicons, images)
├── vage.config.ts     site settings
├── links.lock.json    the websites your pages may link to
├── AGENTS.md          instructions for AI coding assistants
└── .github/           CI checks, dependency updates and an optional live-site check

页面默认是纯 Markdown（.md）。.mdx 页面以及 React 或 Vue 布局需要额外安装几个包：参见 React、Vue 和 MDX。如果页面要用多种语言，参见多语言网站。

常用命令

命令	作用
`npm start`	带实时刷新的开发服务器，会在浏览器中打开
`npm run dev`	同一个服务器，但不打开浏览器（AI 助手用的就是这个）
`npm run check`	查找失效链接、SEO、无障碍和垃圾内容问题；不写入任何内容
`npm run build`	把完成的网站写入 `dist/`
`npm run audit`	页面体积预算和自动化无障碍检查
`npm run preview`	像静态托管平台那样提供 `dist/`

所有命令和选项都在 CLI 参考里。

把 vagejs 加入现有项目

terminal

npm install --save-dev vagejs

然后创建 src/pages/index.md（在它的 frontmatter 里写上 title）和一个 vage.config.ts：

TypeScript

import { defineConfig } from "vagejs";

export default defineConfig({
  site: "https://example.com",
  title: "My Website",
  lang: "en",
});

在 package.json 里添加脚本，让每个人运行相同的命令：

JSON

{
  "scripts": { "dev": "vage dev", "build": "vage build", "check": "vage check", "audit": "vage audit", "preview": "vage preview" }
}

更新 vagejs

terminal

npm outdated vagejs           # see what's available
npm install vagejs@latest     # newest version
npm run check                 # make sure the site still passes

在 vagejs 还处于 0.x 阶段时，新的次版本（比如从 0.10 到 0.11）可能会改变行为。请先阅读更新日志。如果你希望爬虫名称这类服务商信息只在你选择时才改变，可以用 guidelines: { rulePack: "<version>" } 固定规则包的版本。

发布之前

把 vage.config.ts 里的 site 设为你真实的域名。只要它还是 https://example.com，vage check 就会发出警告。
运行 npm run check 并修复所有错误。检查与审核解释了每一项检查结果。
在部署里选择一个托管平台。

下一步：编写你的第一批页面。想看更详细的分步讲解，比如添加第二种语言或一个可交互组件，请参阅指南。