LunariaJS CLI 命令详解：init、build、preview 完全掌握

在前两篇文章中，我们介绍了 LunariaJS 的核心概念和配置方法。今天，让我们深入探讨 LunariaJS 的命令行工具（CLI），掌握每一个命令的用法和最佳实践。

💡 官方文档：LunariaJS 中文文档 - CLI

CLI 概述

LunariaJS 提供了一个功能强大的命令行工具，让你可以：

初始化项目：快速创建配置文件
构建仪表板：生成本地化状态可视化页面
预览仪表板：本地启动服务器查看结果

运行方式

有三种方式运行 LunariaJS CLI：

# 方式 1：使用 npx（推荐，无需安装）
npx lunaria [command]

# 方式 2：使用 npm scripts（推荐）
npm run lunaria:[command]

# 方式 3：直接运行（需要全局或项目安装）
lunaria [command]

全局选项

所有命令都支持以下全局选项：

选项	缩写	说明
`--help`	`-h`	显示帮助信息
`--version`	`-v`	显示版本号
`--config <path>`	`-c`	指定配置文件路径

查看帮助

# 查看主命令帮助
npx lunaria --help

# 查看子命令帮助
npx lunaria init --help
npx lunaria build --help
npx lunaria preview --help

lunaria init - 初始化项目

lunaria init 命令用于快速创建 LunariaJS 配置文件。

基本用法

npx lunaria init

运行后，CLI 会以交互式方式询问配置信息：

? What is the source language of your project? (en)
? What languages do you want to support? (comma-separated, e.g., zh-cn, ja, ko)
? Where are your source files located? (e.g., docs/{slug}.md)
? Where should localized files be stored? (e.g., i18n/{lang}/{slug}.md)
? Where should the dashboard be generated? (lunaria-dashboard)

命令参数

参数	说明	默认值
`--config <path>`	指定输出配置文件路径	`lunaria.config.json`
`--typescript`	生成 TypeScript 配置文件	`false`
`--yes` / `-y`	跳过交互，使用默认值	`false`
`--force` / `-f`	强制覆盖现有配置文件	`false`

交互式初始化流程

让我们看一个完整的交互式初始化示例：

$ npx lunaria init

🌙 LunariaJS - Localization Dashboard Generator

? What is the source language of your project? en
? What languages do you want to support? zh-cn, ja, ko
? Where are your source content files? src/content/docs/{slug}.md
? Where are your localized content files? src/i18n/{lang}/docs/{slug}.md
? Where should the dashboard be output? public/lunaria
? Dashboard title My Docs Localization Status

✨ Created lunaria.config.json

Next steps:
1. Review and adjust lunaria.config.json
2. Run `npx lunaria build` to generate your dashboard
3. Run `npx lunaria preview` to preview locally

生成 TypeScript 配置

如果你更喜欢 TypeScript 配置文件：

npx lunaria init --typescript

这会生成 lunaria.config.ts：

// lunaria.config.ts
import { defineConfig } from '@lunariajs/core';

export default defineConfig({
  sourceLanguage: 'en',
  languages: ['en', 'zh-cn', 'ja', 'ko'],
  files: [
    {
      sourcePath: 'src/content/docs/{slug}.md',
      localizationPath: 'src/i18n/{lang}/docs/{slug}.md',
    },
  ],
  dashboard: {
    outputDir: 'public/lunaria',
    title: 'My Docs Localization Status',
  },
});

快速初始化（跳过交互）

使用 --yes 选项快速创建默认配置：

npx lunaria init --yes

这会使用所有默认值创建配置文件：

{
  "sourceLanguage": "en",
  "languages": ["en"],
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/{slug}.md"
    }
  ],
  "dashboard": {
    "outputDir": "lunaria-dashboard"
  }
}

指定配置文件路径

npx lunaria init --config ./config/lunaria.json

最佳实践

首次使用推荐交互式：让 CLI 引导你完成配置
后续使用 TypeScript：获得更好的类型支持和 IDE 提示
版本控制：将配置文件提交到 Git 仓库

lunaria build - 构建仪表板

lunaria build 命令是 LunariaJS 的核心命令，用于生成本地化仪表板。

基本用法

npx lunaria build

命令参数

参数	说明	默认值
`--config <path>`	指定配置文件路径	`lunaria.config.json`
`--output <dir>`	指定输出目录（覆盖配置）	配置中的 `dashboard.outputDir`
`--silent`	静默模式，不输出日志	`false`
`--verbose`	详细输出模式	`false`

构建过程详解

当你运行 lunaria build 时，LunariaJS 会执行以下步骤：

1. 加载配置文件

📄 Loading configuration from lunaria.config.json...

2. 扫描源文件

🔍 Scanning source files in src/content/docs/...
   Found 42 source files

3. 分析翻译状态

📊 Analyzing translation status...
   - en (source): 42 files
   - zh-cn: 38 done, 3 outdated, 1 missing
   - ja: 30 done, 8 outdated, 4 missing
   - ko: 25 done, 10 outdated, 7 missing

4. 生成仪表板

🎨 Generating dashboard...
   - Creating HTML pages
   - Generating CSS styles
   - Building JavaScript bundle

5. 输出结果

✅ Dashboard generated successfully!
   Output: public/lunaria/
   Files: 15 files, 128KB total

详细输出模式

使用 --verbose 查看更多构建细节：

npx lunaria build --verbose

输出示例：

📄 Loading configuration from lunaria.config.json

🔍 Scanning files...
   Pattern: src/content/docs/{slug}.md
   Files found:
   - src/content/docs/index.md
   - src/content/docs/getting-started.md
   - src/content/docs/configuration.md
   ...

📊 Analyzing translation status...

   File: index.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-27)
   - ja: outdated (modified: 2026-02-20, source newer)
   - ko: missing

   File: getting-started.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-28)
   - ja: done (modified: 2026-02-25)
   - ko: outdated (modified: 2026-02-15, source newer)
   ...

🎨 Generating dashboard...
   - Writing index.html
   - Writing styles.css
   - Writing script.js
   - Writing data/status.json

✅ Build completed in 1.2s
   Output: public/lunaria/

静默模式

在 CI/CD 环境中，可以使用静默模式：

npx lunaria build --silent

自定义输出目录

临时覆盖配置中的输出目录：

npx lunaria build --output ./dist/i18n-dashboard

与 package.json 集成

// package.json
{
  "scripts": {
    "build": "astro build && lunaria build",
    "lunaria:build": "lunaria build",
    "lunaria:build:verbose": "lunaria build --verbose"
  }
}

构建产物

lunaria build 会在输出目录生成以下文件：

lunaria-dashboard/
├── index.html          # 主页面
├── assets/
│   ├── index.css       # 样式文件
│   └── index.js        # JavaScript 逻辑
├── data/
│   └── status.json     # 翻译状态数据
└── favicon.ico         # 网站图标

常见构建错误

错误 1：配置文件未找到

Error: Configuration file not found at lunaria.config.json

解决方案：

# 先运行 init 创建配置
npx lunaria init
# 或指定配置文件路径
npx lunaria build --config ./config/lunaria.json

错误 2：源文件目录不存在

Error: Source directory "docs" does not exist

解决方案：检查 files.sourcePath 配置是否正确。

lunaria preview - 预览仪表板

lunaria preview 命令用于启动本地服务器预览生成的仪表板。

基本用法

npx lunaria preview

命令参数

参数	说明	默认值
`--config <path>`	指定配置文件路径	`lunaria.config.json`
`--port <number>`	指定服务器端口	`3000`
`--open`	自动打开浏览器	`false`
`--host`	监听所有网络接口	`false`

启动预览服务器

$ npx lunaria preview

🌙 LunariaJS Preview Server

Local:   http://localhost:3000
Network: http://192.168.1.100:3000

Press Ctrl+C to stop

指定端口

npx lunaria preview --port 8080

自动打开浏览器

npx lunaria preview --open

允许外部访问

在团队环境中，可以让同事通过局域网访问：

npx lunaria preview --host

预览注意事项

需要先构建：preview 命令不会自动执行构建，确保先运行 lunaria build
热重载：目前不支持热重载，修改配置后需要重新构建
端口冲突：如果默认端口被占用，使用 --port 指定其他端口

命令组合使用场景

开发环境工作流

# 1. 初始化配置（首次）
npx lunaria init

# 2. 构建仪表板
npx lunaria build

# 3. 预览结果
npx lunaria preview --open

与 Astro Starlight 集成

// package.json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build && lunaria build",
    "preview": "astro preview",
    "lunaria:preview": "lunaria preview --port 3001"
  }
}

CI/CD 流水线

# .github/workflows/i18n-check.yml
name: i18n Status Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Build Lunaria Dashboard
        run: npm run lunaria:build -- --silent

      - name: Upload Dashboard
        uses: actions/upload-artifact@v4
        with:
          name: lunaria-dashboard
          path: lunaria-dashboard/

本地调试场景

# 详细输出模式帮助调试
npx lunaria build --verbose

# 如果构建有问题，检查配置
npx lunaria init --force  # 重新生成配置

# 再次构建
npx lunaria build --verbose

CLI 高级技巧

1. 使用环境变量

# 设置 Node.js 环境变量
NODE_ENV=production npx lunaria build

# 自定义环境变量
LUNARIA_OUTPUT=./dist/dashboard npx lunaria build

在配置文件中使用：

// lunaria.config.ts
export default defineConfig({
  dashboard: {
    outputDir: process.env.LUNARIA_OUTPUT || 'lunaria-dashboard',
  },
});

2. 组合多个命令

# 一条命令完成初始化和构建
npx lunaria init --yes && npx lunaria build

# 或使用 npm scripts
npm run lunaria:init && npm run lunaria:build

3. 调试配置问题

# 检查配置文件是否有效
npx lunaria build --verbose 2>&1 | head -20

4. 版本检查

# 查看当前版本
npx lunaria --version

# 查看是否有新版本
npm outdated @lunariajs/core

CLI 常见问题排查

Q1：命令找不到

问题：lunaria: command not found

解决方案：

# 使用 npx
npx lunaria [command]

# 或全局安装
npm install -g @lunariajs/core

Q2：权限被拒绝

问题：EACCES: permission denied

解决方案：

# 检查目录权限
ls -la .

# 或使用 sudo（不推荐）
sudo npx lunaria build

Q3：内存不足

问题：JavaScript heap out of memory

解决方案：

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" npx lunaria build

Q4：构建缓慢

问题：大项目构建时间长

解决方案：

# 检查文件数量
npx lunaria build --verbose | grep "Files found"

# 优化配置，排除不需要的文件

总结

本文详细介绍了 LunariaJS CLI 的三个核心命令：

命令	功能	常用参数
`lunaria init`	初始化配置文件	`--typescript`, `--yes`, `--force`
`lunaria build`	构建本地化仪表板	`--output`, `--silent`, `--verbose`
`lunaria preview`	本地预览仪表板	`--port`, `--open`, `--host`

关键要点：

使用 npx lunaria init 快速开始
lunaria build 是核心命令，生成可视化仪表板
lunaria preview 方便本地调试和预览
将 CLI 命令集成到 package.json scripts 中

下一步

下一篇文章，我们将深入探讨 LunariaJS 本地化仪表板的使用方法，包括：

仪表板界面详解
翻译状态解读
文件状态追踪
筛选与搜索功能
仪表板定制

敬请期待！

💡 推荐阅读：

LunariaJS 中文文档

LunariaJS CLI 参考

LunariaJS 英文文档

LunariaJS 日文文档

LunariaJS 韩文文档