css2class 2.0.0 → 2.0.1

package/bin/class2css.js

@@ -11,6 +11,7 @@ function parseArgs() {
   const args = process.argv.slice(2);
   const options = {
     config: './class2css.config.js',
+    configProvided: false,
     watch: true,
     help: false,
     version: false,
@@ -32,6 +33,7 @@ function parseArgs() {
       case '--config':
       case '-c':
         options.config = args[++i];
+        options.configProvided = true;
         break;
       case '--no-watch':
         options.watch = false;
@@ -161,11 +163,37 @@ function showVersion() {
 }
 
 // 检查配置文件是否存在
-function checkConfig(configPath) {
+function checkConfig(configPath, configProvided) {
   const absolutePath = path.resolve(configPath);
   if (!fs.existsSync(absolutePath)) {
-    console.error(`Configuration file not found: ${absolutePath}`);
-    console.error('Please create a class2css.config.js file or specify a valid config path.');
+    const isDefaultConfig =
+      !configProvided && path.resolve('./class2css.config.js') === absolutePath;
+
+    console.error(`配置文件不存在：${absolutePath}`);
+
+    if (isDefaultConfig) {
+      console.error(`
+首次运行提示：
+- 你当前没有在项目根目录找到默认配置：./class2css.config.js
+
+你可以选择以下任意一种方式启动：
+1) 直接运行内置示例（无需复制配置）：
+   - npm run example:weapp
+   - npm run example:web
+
+2) 直接指定示例配置运行：
+   - node bin/class2css.js --config ./examples/weapp/class2css.config.js
+   - node bin/class2css.js --config ./examples/web/class2css.config.js
+
+3) 复制示例配置到项目根目录（推荐用于你自己的项目）：
+   - 复制 ./examples/weapp/class2css.config.js  ->  ./class2css.config.js
+   - 复制 ./examples/weapp/styles.config.js    ->  ./styles.config.js
+   （或者选择 web 示例同路径）
+`);
+    } else {
+      console.error('请创建 class2css.config.js，或使用 -c/--config 指定有效配置文件路径。');
+    }
+
     process.exit(1);
   }
   return absolutePath;
@@ -238,7 +266,7 @@ async function main() {
     }
 
     // 检查配置文件
-    const configPath = checkConfig(options.config);
+    const configPath = checkConfig(options.config, options.configProvided);
 
     console.log('🚀 Starting Class2CSS...');
     console.log(`📁 Config: ${configPath}`);

package/common.css

@@ -1,3 +1,3 @@
-.bg{
+.bg-red{
     background-color: #f00;
 }

package/configs/typography.config.js

@@ -23,6 +23,7 @@ module.exports = {
   // 行高
   lineHeight: {
     leading: 'line-height',
+    lh: 'line-height',
   },
 
   // 字间距

package/docs/.vitepress/config.mjs

@@ -1,65 +1,68 @@
-/*
- * @LastEditors: biz
- */
-import { defineConfig } from 'vitepress';
-
-export default defineConfig({
-  title: 'Class2CSS',
-  description: '企业级原子化CSS生成工具，支持智能单位处理、配置验证、性能缓存和向后兼容',
-  lang: 'zh-CN',
-
-  themeConfig: {
-    nav: [
-      { text: '文档', link: '/guide/getting-started' },
-      { text: '参考', link: '/guide/config' },
-      { text: 'FAQ', link: '/guide/faq' },
-    ],
-
-    sidebar: {
-      '/guide/': [
-        {
-          text: '开始',
-          items: [
-            { text: '快速开始', link: '/guide/getting-started' },
-          ],
-        },
-        {
-          text: '核心概念',
-          items: [
-            { text: '类名语法与生成规则', link: '/guide/concepts' },
-            { text: '单位与转换策略', link: '/guide/units' },
-            { text: 'Important 与静态类', link: '/guide/important-and-static' },
-          ],
-        },
-        {
-          text: '参考',
-          items: [
-            { text: 'CLI', link: '/guide/cli' },
-            { text: '规则参考', link: '/guide/rules-reference' },
-            { text: '配置模板（可复制）', link: '/guide/config-template' },
-            { text: '配置', link: '/guide/config' },
-          ],
-        },
-        {
-          text: '进阶',
-          items: [
-            { text: '增量模式（只增不删）', link: '/guide/incremental' },
-          ],
-        },
-        {
-          text: '帮助',
-          items: [{ text: '常见问题', link: '/guide/faq' }],
-        },
-      ],
-    },
-
-    socialLinks: [{ icon: 'github', link: 'https://github.com/wnagchi/css2class' }],
-
-    search: {
-      provider: 'local',
-    },
-
-    outline: { level: [2, 3] },
-  },
-});
-
+/*
+ * @LastEditors: biz
+ */
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  // GitHub Pages（Project Pages）部署路径： https://<user>.github.io/<repo>/
+  // 所以这里必须设置为 `/<repo>/`（末尾带 /）
+  base: '/css2class/',
+  title: 'Class2CSS',
+  description: '企业级原子化CSS生成工具，支持智能单位处理、配置验证、性能缓存和向后兼容',
+  lang: 'zh-CN',
+
+  themeConfig: {
+    nav: [
+      { text: '文档', link: '/guide/getting-started' },
+      { text: '参考', link: '/guide/config' },
+      { text: 'FAQ', link: '/guide/faq' },
+    ],
+
+    sidebar: {
+      '/guide/': [
+        {
+          text: '开始',
+          items: [
+            { text: '快速开始', link: '/guide/getting-started' },
+          ],
+        },
+        {
+          text: '核心概念',
+          items: [
+            { text: '类名语法与生成规则', link: '/guide/concepts' },
+            { text: '单位与转换策略', link: '/guide/units' },
+            { text: 'Important 与静态类', link: '/guide/important-and-static' },
+          ],
+        },
+        {
+          text: '参考',
+          items: [
+            { text: 'CLI', link: '/guide/cli' },
+            { text: '规则参考', link: '/guide/rules-reference' },
+            { text: '配置模板（可复制）', link: '/guide/config-template' },
+            { text: '配置', link: '/guide/config' },
+          ],
+        },
+        {
+          text: '进阶',
+          items: [
+            { text: '增量模式（只增不删）', link: '/guide/incremental' },
+          ],
+        },
+        {
+          text: '帮助',
+          items: [{ text: '常见问题', link: '/guide/faq' }],
+        },
+      ],
+    },
+
+    socialLinks: [{ icon: 'github', link: 'https://github.com/wnagchi/css2class' }],
+
+    search: {
+      provider: 'local',
+    },
+
+    outline: { level: [2, 3] },
+  },
+});
+

package/docs/guide/cli.md

@@ -1,97 +1,97 @@
-# CLI 使用说明
-
-CLI 适合在 CI 或本地快速覆盖配置（例如临时换输入/输出目录）。你可以直接运行 `class2css`，或者在项目里通过 npm scripts 间接运行。
-
-## 基本用法
-
-```bash
-class2css [options]
-```
-
-:::tip
-如果你是通过本项目自带脚本运行（例如 `npm run start`），本质上也是把参数传给 `class2css`。
-:::
-
-## 参数一览
-
-### 配置与模式
-
-- **`-c, --config <path>`**：指定配置文件路径（默认 `./class2css.config.js`）
-- **`--no-watch`**：关闭监听模式（执行一次扫描后退出）
-
-### 运行时覆盖（覆盖配置文件）
-
-- **`-i, --input <path>`**：覆盖输入目录（扫描/监听入口）
-  - 目前该参数为**单路径**覆盖（对应 `multiFile.entry.path` 的单值用法）
-  - 如需多目录/多文件入口，请在配置中使用 `multiFile.entry.path: string[]`
-- **`-o, --output <path>`**：覆盖输出目录
-- **`-f, --output-file <name>`**：覆盖输出文件名
-- **`-t, --output-type <type>`**：覆盖输出类型（`filePath` 或 `uniFile`）
-
-### 文档服务
-
-- **`--docs`**：启用文档服务（与主程序并行运行）
-- **`--docs-port <port>`**：指定文档服务端口（默认 5173；若占用则自动寻找下一个可用端口）
-- **`--docs-host <host>`**：指定文档服务主机（默认 `127.0.0.1`）
-- **`--docs-open`**：启动后自动打开浏览器
-- **`--docs-only`**：只启动文档服务，不启动 class2css 主流程
-
-### 其他
-
-- **`-h, --help`**：显示帮助信息
-- **`-v, --version`**：显示版本信息
-
-## 使用示例
-
-### 基本使用
-
-```bash
-# 默认配置启动（监听模式）
-class2css
-
-# 使用自定义配置文件
-class2css -c ./my-config.js
-
-# 单次构建（不监听）
-class2css --no-watch
-```
-
-### 运行时覆盖
-
-```bash
-# 覆盖输入和输出目录
-class2css -i ./src -o ./dist
-
-# 覆盖输入、输出和文件名
-class2css -i ./pages -o ./styles -f app.wxss
-
-# 覆盖输出类型
-class2css -i ./src -o ./dist -t uniFile
-```
-
-### 文档服务
-
-```bash
-# 启动工具并同时开启文档服务
-class2css --docs
-
-# 启动文档服务并自动打开浏览器
-class2css --docs --docs-open
-
-# 指定文档服务端口
-class2css --docs --docs-port 8080
-
-# 只启动文档服务（不运行主程序）
-class2css --docs-only
-```
-
-## 注意事项
-
-1. 运行时覆盖的参数会覆盖配置文件中的对应设置
-2. 文档服务默认监听 `127.0.0.1`，只能本地访问
-3. 如果指定端口被占用，工具会自动寻找下一个可用端口
-4. 使用 `--docs-only` 时，不会执行任何 CSS 生成操作
-
-## 下一步
-
-- 了解配置结构与最佳实践：阅读 [配置指南](./config.md)
+# CLI 使用说明
+
+CLI 适合在 CI 或本地快速覆盖配置（例如临时换输入/输出目录）。你可以直接运行 `class2css`，或者在项目里通过 npm scripts 间接运行。
+
+## 基本用法
+
+```bash
+class2css [options]
+```
+
+:::tip
+如果你是通过本项目自带脚本运行（例如 `npm run start`），本质上也是把参数传给 `class2css`。
+:::
+
+## 参数一览
+
+### 配置与模式
+
+- **`-c, --config <path>`**：指定配置文件路径（默认 `./class2css.config.js`）
+- **`--no-watch`**：关闭监听模式（执行一次扫描后退出）
+
+### 运行时覆盖（覆盖配置文件）
+
+- **`-i, --input <path>`**：覆盖输入目录（扫描/监听入口）
+  - 目前该参数为**单路径**覆盖（对应 `multiFile.entry.path` 的单值用法）
+  - 如需多目录/多文件入口，请在配置中使用 `multiFile.entry.path: string[]`
+- **`-o, --output <path>`**：覆盖输出目录
+- **`-f, --output-file <name>`**：覆盖输出文件名
+- **`-t, --output-type <type>`**：覆盖输出类型（`filePath` 或 `uniFile`）
+
+### 文档服务
+
+- **`--docs`**：启用文档服务（与主程序并行运行）
+- **`--docs-port <port>`**：指定文档服务端口（默认 5173；若占用则自动寻找下一个可用端口）
+- **`--docs-host <host>`**：指定文档服务主机（默认 `127.0.0.1`）
+- **`--docs-open`**：启动后自动打开浏览器
+- **`--docs-only`**：只启动文档服务，不启动 class2css 主流程
+
+### 其他
+
+- **`-h, --help`**：显示帮助信息
+- **`-v, --version`**：显示版本信息
+
+## 使用示例
+
+### 基本使用
+
+```bash
+# 默认配置启动（监听模式）
+class2css
+
+# 使用自定义配置文件
+class2css -c ./my-config.js
+
+# 单次构建（不监听）
+class2css --no-watch
+```
+
+### 运行时覆盖
+
+```bash
+# 覆盖输入和输出目录
+class2css -i ./src -o ./dist
+
+# 覆盖输入、输出和文件名
+class2css -i ./pages -o ./styles -f app.wxss
+
+# 覆盖输出类型
+class2css -i ./src -o ./dist -t uniFile
+```
+
+### 文档服务
+
+```bash
+# 启动工具并同时开启文档服务
+class2css --docs
+
+# 启动文档服务并自动打开浏览器
+class2css --docs --docs-open
+
+# 指定文档服务端口
+class2css --docs --docs-port 8080
+
+# 只启动文档服务（不运行主程序）
+class2css --docs-only
+```
+
+## 注意事项
+
+1. 运行时覆盖的参数会覆盖配置文件中的对应设置
+2. 文档服务默认监听 `127.0.0.1`，只能本地访问
+3. 如果指定端口被占用，工具会自动寻找下一个可用端口
+4. 使用 `--docs-only` 时，不会执行任何 CSS 生成操作
+
+## 下一步
+
+- 了解配置结构与最佳实践：阅读 [配置指南](./config.md)

package/docs/guide/config-template.md

@@ -1,6 +1,11 @@
 # 配置模板（可复制）
 
-本页把仓库里的 `class2css.config.js`（你现在已经跑通、并且覆盖了当前支持能力）整理成一份**可直接复制**的模板，避免开发者每个项目都从零拼配置。
+本仓库内置两套**可直接复制**的示例配置，避免每个项目都从零拼配置：
+
+- **小程序（wxss / rpx）**：`examples/weapp/`
+- **Web（css / px）**：`examples/web/`
+
+你可以直接复制对应目录里的 `class2css.config.js` + `styles.config.js` 到你的项目里使用（也可以用 `-c` 指定示例配置路径运行）。
 
 :::tip 配置结构说明
 配置已拆分为两个文件：
@@ -16,6 +21,16 @@
 - `multiFile.output.path` / `multiFile.output.fileName`：统一输出文件位置（`cssOutType='uniFile'` 时）
 :::
 
+## Web 场景配置差异（对照）
+
+如果你是 Web 项目（输出 css / 默认 px），主要差异在：
+
+- `system.baseUnit: 'px'`
+- `system.unitConversion: 1`
+- `multiFile.entry.fileType: ['html', 'vue']`（按你项目模板扩展名调整）
+- `multiFile.output.fileName: 'styles.css'`
+- `multiFile.output.fileType: 'css'`（仅 `cssOutType='filePath'` 时生效）
+
 ## 工具配置文件（class2css.config.js）
 
 ```js