Astro 命令使用指南
本文基于 Astro 4.x 稳定版 整理，覆盖从项目创建、开发调试、生产构建到工具运维的全流程命令，包含参数详解、使用示例、场景速查与常见避坑指南。
一、前置说明
1. 命令执行方式
Astro 命令有两种执行方式：
- 项目内执行：通过
package.json脚本调用（推荐），格式为npm run <脚本名> - 直接调用：通过包管理器执行原生 Astro 命令，格式为
npx astro <子命令>（pnpm/yarn/bun 对应写法见下文）
2. 传参规则
通过 npm run 执行脚本时，额外参数必须用 -- 分隔，否则参数会被 npm 自身捕获而非传给 Astro。
# 正确写法
npm run dev -- --port 3000
# 错误写法（参数不生效）
npm run dev --port 3000
pnpm/yarn/bun 兼容上述写法，也支持直接传参（如 pnpm dev --port 3000）。
3. 不同包管理器命令对照表
| 功能 | npm | pnpm | yarn | bun |
|---|---|---|---|---|
| 创建项目 | npm create astro@latest | pnpm create astro | yarn create astro | bun create astro |
| 启动开发服务 | npm run dev | pnpm dev | yarn dev | bun dev |
| 生产构建 | npm run build | pnpm build | yarn build | bun build |
| 预览构建产物 | npm run preview | pnpm preview | yarn preview | bun preview |
| 执行原生命令 | npx astro <子命令> | pnpm astro <子命令> | yarn astro <子命令> | bunx astro <子命令> |
4. 全局通用参数
所有 Astro 子命令都支持以下基础参数：
| 参数 | 说明 |
|---|---|
-h, --help | 显示当前命令的帮助信息与全部参数 |
-v, --version | 显示当前项目的 Astro 版本 |
--verbose | 输出详细的调试日志，用于排查问题 |
--silent | 静默模式，仅输出错误信息 |
二、项目初始化与创建命令
1. create astro：创建新项目
Astro 官方提供的交互式脚手架，用于快速生成项目模板，是所有 Astro 项目的起点。
基础用法
# 交互式创建（推荐新手）
npm create astro@latest
# 指定项目目录直接创建
npm create astro@latest my-astro-site
常用参数
| 参数 | 说明 |
|---|---|
--template <模板名> | 指定官方模板跳过模板选择步骤，支持 basics blog docs portfolio minimal 等 |
--yes, -y | 跳过所有交互式确认，使用默认配置全自动创建 |
--install | 自动安装依赖（默认交互式会询问） |
--no-install | 跳过依赖安装，后续手动执行 |
--typescript <模式> | 指定 TypeScript 配置模式：strict（严格）/ strictest（最严格）/ base（基础） |
--git | 自动初始化 Git 仓库 |
--no-git | 不初始化 Git 仓库 |
使用示例
# 1. 一键创建博客模板项目，自动装依赖、初始化Git
npm create astro@latest my-blog -- --template blog --yes --git --install
# 2. 创建最精简的基础项目，不装依赖
npm create astro@latest minimal-site -- --template minimal --no-install
# 3. 创建严格 TypeScript 模式的文档站
npm create astro@latest docs-site -- --template docs --typescript strict
注意事项
- 官方模板可在 Astro 模板市场 查看，第三方模板需手动克隆
- 命令末尾的
@latest确保每次都使用最新版脚手架，避免生成旧版本项目
三、核心开发与运行命令
1. astro dev：启动开发服务器
最常用的开发命令，启动本地热更新开发服务器，支持热模块替换（HMR），代码修改后页面实时刷新，无需手动重启。
基础用法
# package.json 默认脚本
npm run dev
# 原生调用
npx astro dev
常用参数
| 参数 | 说明 |
|---|---|
--host <地址> | 指定服务器监听的主机地址。默认 localhost，设为 0.0.0.0 可让局域网内设备访问 |
--port <端口号> | 指定服务端口，默认值为 4321 |
--open | 服务启动后自动在系统默认浏览器打开页面 |
--open <浏览器名> | 指定浏览器打开，如 --open firefox |
--no-port-hopping | 禁止端口自动跳转。默认端口被占用时会自动寻找下一个可用端口，加此参数则直接报错退出 |
--base <路径> | 临时指定站点基础路径，覆盖 astro.config.mjs 中的配置 |
--site <域名> | 临时指定站点完整域名，影响绝对路径生成 |
--drafts | 显示标记为草稿的内容集合（开发模式默认已开启） |
--no-drafts | 开发模式下隐藏草稿内容 |
使用示例
# 1. 局域网可访问，端口设为 3000，启动后自动打开
npm run dev -- --host 0.0.0.0 --port 3000 --open
# 2. 固定端口 4321，被占用则直接退出
npm run dev -- --no-port-hopping
# 3. 开发时隐藏草稿文章
npm run dev -- --no-drafts
注意事项
- 开发模式下代码不做压缩优化，产物保留完整调试信息
- 环境变量自动加载
.env和.env.development文件 - 内容集合的 schema 修改后会自动同步类型，无需手动执行同步命令
2. astro build：生产环境构建
将项目编译为可部署的生产产物，默认输出到 dist 目录。静态模式生成纯 HTML/CSS/JS，SSR 模式生成对应适配器的服务端代码。
基础用法
# package.json 默认脚本
npm run build
# 原生调用
npx astro build
常用参数
| 参数 | 说明 |
|---|---|
--outDir <路径> | 指定构建产物输出目录，默认 dist，覆盖配置文件 |
--site <完整域名> | 指定站点根域名，如 https://example.com，影响 sitemap、canonical 链接、静态资源绝对路径 |
--base <路径> | 指定站点基础路径，用于部署到子目录（如 GitHub Pages 子仓库），例：--base /my-blog/ |
--drafts | 构建时包含标记为草稿的内容（生产构建默认排除草稿） |
--no-drafts | 强制排除草稿，覆盖配置文件 |
--force | 强制全量重新构建，忽略缓存 |
--dry-run | 模拟构建流程，不生成实际文件，用于验证配置 |
使用示例
# 1. 构建到 output 目录，指定站点域名
npm run build -- --outDir output --site https://www.myblog.com
# 2. 部署到 GitHub Pages 子仓库，指定 base 路径
npm run build -- --base /my-astro-blog/
# 3. 构建包含草稿文章，用于内部预览
npm run build -- --drafts
注意事项
- 生产构建会自动做代码压缩、资源优化、Tree Shaking，体积远小于开发模式
- 环境变量自动加载
.env和.env.production文件 - SSR 模式下产物包含服务端运行代码，不能直接用静态服务器部署，需配合对应适配器
- 构建失败时加
--verbose参数可输出详细错误日志，方便排查
3. astro preview：本地预览构建产物
启动一个轻量静态服务器，在本地预览 astro build 生成的生产产物，用于验证构建结果是否符合预期。
基础用法
# package.json 默认脚本
npm run preview
# 原生调用
npx astro preview
常用参数
和 astro dev 通用核心参数：--host --port --open --base
使用示例
# 预览构建产物，局域网可访问，端口 8080
npm run preview -- --host 0.0.0.0 --port 8080 --open
注意事项
- 必须先执行构建：
preview仅读取已有构建产物，未执行astro build会报错 - 仅用于本地预览验证，不能作为生产服务器使用，无性能优化和安全防护
- SSR 模式下部分适配器不支持
preview命令，需按适配器文档本地启动服务 - 环境变量加载规则和生产构建一致，读取
.env.production
四、集成与插件管理命令
astro add：一键安装官方集成
Astro 官方提供的集成安装工具，自动完成依赖安装 + 配置文件修改，无需手动编辑 astro.config.mjs，是接入官方生态的首选方式。
基础用法
npx astro add <集成名>
# 跳过交互式确认，全自动安装
npx astro add <集成名> --yes
支持的官方集成分类
| 分类 | 常用集成名 | 作用 |
|---|---|---|
| UI 框架 | react vue svelte preact solid-js lit | 在 Astro 项目中使用对应框架组件 |
| SSR 适配器 | node vercel netlify cloudflare deno | 开启服务端渲染，适配对应部署平台 |
| CSS 工具 | tailwind | 一键接入 Tailwind CSS |
| 内容功能 | mdx sitemap rss | 支持 MDX、自动生成站点地图、RSS 订阅 |
| 性能优化 | partytown | 第三方脚本离线执行，优化首屏性能 |
| 前端框架 | alpinejs | 接入 Alpine.js 交互框架 |
使用示例
# 1. 接入 React 支持
npx astro add react
# 2. 同时安装 Tailwind 和 MDX，跳过确认
npx astro add tailwind mdx --yes
# 3. 接入 Vercel SSR 适配器
npx astro add vercel
# 4. 生成站点地图和 RSS 订阅
npx astro add sitemap rss
注意事项
- 仅
@astrojs/开头的官方集成支持astro add，第三方集成需手动安装配置 - 集成名支持简写，如
tailwind会自动对应@astrojs/tailwind - 执行后会自动备份原配置文件，配置冲突时可手动回滚
五、类型与内容集合命令
1. astro check：全项目类型检查
对整个项目执行 TypeScript 类型校验，包括 .astro 组件、.ts 文件、内容集合 schema，提前发现类型错误，常用于 CI/CD 流水线。
基础用法
npx astro check
常用参数
| 参数 | 说明 |
|---|---|
--watch | 监听文件变化，增量执行类型检查，开发时实时校验 |
--error-warnings | 将所有警告视为错误，检查不通过则退出码非 0，适合 CI 严格校验 |
使用示例
# 1. CI 流水线严格类型校验，警告即失败
npx astro check --error-warnings
# 2. 开发时实时监听类型错误
npx astro check --watch
注意事项
- 依赖项目根目录的
tsconfig.json，Astro 项目默认自动生成 - 仅检查类型错误，不校验代码风格，代码规范检查需配合 ESLint
- 类型检查不通过不影响构建，建议部署前强制校验
2. astro sync：同步内容集合类型
根据 src/content/config.ts 中的 schema 定义，自动生成内容集合的 TypeScript 类型定义，让导入内容时获得完整的类型提示和校验。
基础用法
npx astro sync
常用参数
| 参数 | 说明 |
|---|---|
--force | 强制重新生成类型文件，覆盖旧文件 |
使用场景
- 修改了内容集合的 schema 后，IDE 类型提示不更新
- 导入内容时报类型不存在错误
- 升级 Astro 大版本后类型异常
注意事项
- 生成的类型文件存放在项目根目录
.astro文件夹下，无需手动编辑 - 开发模式下 Astro 会自动同步类型，绝大多数场景无需手动执行此命令
- 类型异常时优先执行
--force强制同步，多数问题可解决
六、工具与辅助命令
1. astro info：输出项目环境信息
打印完整的项目运行环境信息，包括 Astro 版本、Node 版本、操作系统、包管理器、适配器、已安装集成，是排查问题、提交 Issue 时的必备信息。
用法
npx astro info
输出示例
Astro v4.16.0
Node v20.17.0
System macOS (arm64)
Package Manager pnpm
Output static
Adapter none
Integrations @astrojs/tailwind
@astrojs/mdx
@astrojs/sitemap
2. astro telemetry：遥测数据管理
管理 Astro 的匿名使用数据收集，默认开启。仅收集匿名功能使用数据，不会收集项目代码、内容等隐私信息。
用法
# 查看当前遥测状态
npx astro telemetry status
# 关闭遥测
npx astro telemetry disable
# 开启遥测
npx astro telemetry enable
3. astro preferences：CLI 全局偏好设置
配置 Astro CLI 的全局行为偏好，设置后对所有本地 Astro 项目生效。
常用用法
# 列出所有偏好设置与当前值
npx astro preferences list
# 设置某项偏好
npx astro preferences set <配置项> <值>
# 重置所有偏好为默认值
npx astro preferences reset
常用配置项
| 配置项 | 说明 | 默认值 |
|---|---|---|
dev.portHop | 端口被占用时是否自动跳转 | true |
cli.color | 输出是否启用彩色日志 | true |
telemetry.enabled | 是否启用遥测 | true |
示例
# 全局禁用自动端口跳转
npx astro preferences set dev.portHop false
七、高频场景命令速查表
| 场景 | 命令 |
|---|---|
| 新手创建默认博客项目 | npm create astro@latest my-blog -- --template blog --yes |
| 日常本地开发 | npm run dev |
| 给同事分享预览，局域网访问 | npm run dev -- --host 0.0.0.0 |
| 内容集合类型提示异常 | npx astro sync --force |
| 部署前类型校验 | npx astro check --error-warnings |
| 生产环境构建 | npm run build |
| 本地验证构建结果 | npm run preview |
| 添加 Tailwind CSS | npx astro add tailwind --yes |
| 添加 React 支持 | npx astro add react --yes |
| 排查问题输出版本信息 | npx astro info |
| 部署到 GitHub Pages 子仓库 | npm run build -- --base /仓库名/ |
八、最佳实践与避坑指南
1. 脚本自定义优化
建议在 package.json 中封装常用参数，避免每次手动输入：
{
"scripts": {
"dev": "astro dev --host 0.0.0.0",
"build": "astro build --site https://your-domain.com",
"check": "astro check --error-warnings",
"sync": "astro sync --force"
}
}
2. CI/CD 标准流程
# 1. 安装依赖（锁定版本）
npm ci
# 2. 类型检查
npx astro check --error-warnings
# 3. 生产构建
npm run build
3. 常见问题排查
- 命令参数不生效：检查
npm run后是否加了--分隔符 - 端口被占用：加
--port指定其他端口，或用--no-port-hopping确认端口占用 - 环境变量不生效：确认文件名对应运行模式（开发用
.env.development，生产用.env.production） - 构建后页面空白：检查
--base路径是否正确，静态资源路径是否匹配部署环境 - 类型提示异常：优先执行
npx astro sync --force，再重启 IDE 类型服务
4. 版本升级注意事项
- 升级 Astro 版本后，建议先执行
npx astro sync --force同步类型 - 大版本升级参考官方迁移文档，不要直接跨大版本升级
- 升级后同步升级所有官方集成，避免版本不兼容