CLI 命令

Astro 提供一套命令行工具（CLI），用来开发、构建、预览和检查项目。所有命令都能用 npx astro [命令] [标志] 的形式跑；更常见的做法是在 package.json 里配好脚本，比如 npm run dev。本章挑日常最高频的命令讲，不求列全。

astro dev：启动开发服务器

astro dev 启动本地开发服务器（不打包资源、支持热更新 HMR）。你平时写代码基本就靠它。常用标志：

• --port <数字>：指定端口，默认 4321。
• --host [地址]：允许非本机 IP 访问（比如手机连同一局域网预览），别用在生产。
• --open [地址]：启动后自动打开浏览器。
• --verbose：打印详细日志。

v7 里 dev 还支持后台运行与子命令：astro dev stop 停止后台服务、astro dev status 看状态、astro dev logs 看日志。终端里按 s 同步内容层、按 o 开浏览器、按 q 退出。

astro build：构建站点

astro build 把站点构建成可部署的产物。默认生成静态文件到 dist/；按需渲染的路由会额外生成服务端文件。常见标志：

• --devOutput（v5+）：输出接近 dev 模式的构建，带调试信息。
• --outDir <路径>：覆盖输出目录。

astro preview：预览构建产物

astro preview 启动一个本地服务器，用来预览 astro build 生成的 dist/。它适合在真正部署前抓一些只有构建后才暴露的问题。它不是生产服务器，只是预览。v7.2.0+ 同样支持 --background 及 stop / status / logs 子命令。

astro check：类型检查

astro check 对项目跑诊断，比如检查 .astro 文件的类型错误。一旦发现错误，退出码为 1，所以很适合接在 CI（持续集成）里。常用标志：

• --watch：监听文件变更并持续报错。
• --minimumFailingSeverity <error|warning|hint>：把什么级别算作”失败”，默认 error。
• --noSync：检查前不先跑 astro sync。

astro sync：生成类型

astro sync（v2+）生成 Astro 各模块的 TypeScript 类型，比如 .astro/types.d.ts，以及 astro:content、astro:env、astro:actions 这些虚拟模块的类型。不用担心漏跑——dev / build / check 都会自动先触发它。

astro add：加集成

astro add 往配置里加集成（第 39 章），自动装包并改好 astro.config.mjs：

npx astro add react

astro info：环境信息

astro info 打印当前 Astro 环境信息（版本、Node、适配器、集成等），方便你提 issue 时贴给别人。astro info --copy 直接复制到剪贴板。开发工具栏里的”复制调试信息”按钮，底层就是调它。

astro preferences：用户偏好

astro preferences 管理用户偏好，存为项目级（.astro/settings.json）或全局。可用的偏好有 devToolbar（默认开）、checkUpdates（默认开）。子命令：list、enable、disable、reset。例如：

astro preferences disable devToolbar          # 当前项目关掉开发工具栏
astro preferences disable --global devToolbar # 本机所有 Astro 项目都关

astro telemetry：遥测开关

astro telemetry 设置是否发送匿名使用统计。子命令：disable、enable、reset。例如 astro telemetry disable，或者设环境变量 ASTRO_TELEMETRY_DISABLED。

其他小命令

• astro docs：在终端直接打开 Astro 文档站。
• astro create-key：生成一个密钥，用于加密服务端岛屿传递的 props（设为环境变量 ASTRO_KEY）。

通用标志

下面这些标志可被 dev、build、preview 等命令接受：

• --root <路径>：指定项目根目录。
• --config <路径>：指定配置文件（默认 astro.config.mjs）。
• --site <网址> / --base <路径>：临时覆盖配置里的 site、base。
• --host / --port / --open：上面讲过。
• --verbose / --silent：详细日志 / 无输出。
• --json（v7+）：用 JSON 格式输出日志。

怎么随时查帮助

任何命令后面加 --help 都能看它支持的标志，比如 astro build --help。想确认装的是哪个版本，用 astro --version。这两个全局标志最实用。

一条命令的常见实战组合

日常你最常用的是这几条，放在 package.json 脚本里最顺手：

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}

这样 npm run dev 起开发、npm run build 先查类型再构建、npm run preview 预览。

命令速查表

命令	干嘛用
astro dev	起开发服务器，热更新
astro build	构建成可部署产物
astro preview	本地预览构建结果
astro check	类型检查（CI 友好）
astro sync	生成虚拟模块类型
astro add	加集成
astro info	打印环境信息
astro preferences	管理用户偏好
astro telemetry	遥测开关

dev 和 build 的底层区别

dev 为了开发快，不做完整打包、保留源码便于调试；build 则会真正打包、压缩、产出 dist/。所以”本地好好的，构建后坏了”时有发生——差异往往就在打包阶段。这也是为什么 preview 值得跑：它预览的是 build 的产物，能提前抓到只在构建后才出现的问题。

preview 不是生产服务器

astro preview 只是方便你本地看构建结果，性能和稳定性都不能代表真实生产环境。真正上线请用各平台的部署流程（第 50、51 章），或 Node 适配器输出的服务器程序。别把 preview 当成生产服务长期跑。

常见报错与排查

• Cannot find package 'astro'：依赖没装，先 npm install。
• 端口被占用：astro dev --port 4000 换一个。
• astro check 退出码 1：说明有类型错误，按它列出的文件逐条修。
• 构建卡住：多半是某个按需路由没装适配器（第 40 章），或某依赖不兼容当前 Node 版本。

记住一个万能动作：任何命令加 --help，看它支持哪些标志，比瞎搜快得多。

在 CI 里怎么用

持续集成（CI，每次推代码自动跑检查/构建）里，通常只跑 astro check 和 astro build，不跑 dev / preview。例如 CI 脚本写 npm run build（它内部是 astro check && astro build），一旦有类型错误，构建直接失败、Pipeline 变红，把问题挡在合并前。这也是为什么前面强调把 check 接进 build 脚本——它让 CI 真正有用。

你可能还想问

• 命令卡住不动？ 先 Ctrl+C 退出，再跑 --help 看是否要加必填标志；很多命令缺参数会一直等输入。
• 想看某个命令的所有标志？ 除了 --help，也可以直接翻官方 CLI 参考，v7 的标志每年都有微调，以官方为准。
• npx astro 和 npm run 哪个好？ 项目里推荐用 npm run，脚本写在 package.json 里更直观；临时试一条命令时用 npx astro 更快。

小结

日常最高频的命令就五条：astro dev 开发、astro build 构建、astro preview 预览、astro check 查类型、astro sync 生成类型。再加 astro add 装集成、astro info 看环境、astro preferences 管偏好。拿不准就用 --help。这些命令和前面的配置、集成知识是配套的：配置写在文件里，命令负责把它跑起来。

下一章我们深入 TypeScript：Astro 内建的类型支持到底怎么用。