# 快速开始 一分钟，网站就能跑起来。

> 如何安装 vagejs 并开始使用：环境要求、一条命令创建网站、把 vagejs 加入现有项目，以及如何安全地更新。

安装 vagejs 需要 Node.js 22.12 或更高版本。然后运行 `npm create vagejs@latest my-site`，它会新建一个网站、完成安装，并在浏览器里打开。本页还介绍了如何把 vagejs 加入现有项目，以及如何更新它。

更新于 2026年10月28日

## 环境要求

-   **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** 会打开这个文件夹，并把提示词打印出来，供你粘贴到它的聊天窗口里。
-   **浏览器编辑器**会在网站旁边打开，并为你的新网站列出一份[后续步骤](https://vagejs.com/docs/content-authoring/#edit-in-your-browser)。

或者直接编辑 `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**，请参阅[故障排除](https://vagejs.com/docs/troubleshooting/#http-431-in-the-browser)。

## 你会得到什么

想看看最终效果？[案例](https://vagejs.com/showcase/)（英文）里有三个用同一个起始模板搭建的完整网站，并附有源代码。

```
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](https://vagejs.com/docs/components/)。如果页面要用多种语言，参见[多语言网站](https://vagejs.com/docs/multi-language/)。

## 常用命令

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

所有命令和选项都在 [CLI 参考](https://vagejs.com/docs/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）可能会改变行为。请先阅读[更新日志](https://vagejs.com/changelog/)。如果你希望爬虫名称这类服务商信息只在你选择时才改变，可以用 `guidelines: { rulePack: "<version>" }` 固定规则包的版本。

## 发布之前

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

下一步：[编写你的第一批页面](https://vagejs.com/docs/content-authoring/)。想看更详细的分步讲解，比如添加第二种语言或一个可交互组件，请参阅[指南](https://vagejs.com/guides/)。