Stylus 安装与配置 #

环境要求 #

在安装 Stylus 之前，请确保你的系统已安装：

依赖 版本要求 检查命令
Node.js >= 12.0 node -v
npm >= 6.0 npm -v

安装方式 #

方式一：全局安装 #

使用 npm 全局安装 Stylus：

bash 
npm install -g stylus

安装完成后，验证安装：

bash 
stylus --version
# 输出：stylus 0.x.x

方式二：项目本地安装 #

推荐在项目中本地安装：

bash 
npm install stylus --save-dev

然后在 package.json 中添加脚本：

json 
{
  "scripts": {
    "build:css": "stylus src/styles/main.styl -o dist/css",
    "watch:css": "stylus -w src/styles/main.styl -o dist/css"
  }
}

运行命令：

bash 
npm run build:css
npm run watch:css

命令行使用 #

基本命令 #

bash 
# 编译单个文件
stylus src/main.styl -o dist/

# 编译并压缩
stylus src/main.styl -o dist/ --compress

# 监听文件变化
stylus -w src/main.styl -o dist/

# 监听目录
stylus -w src/ -o dist/

# 输出到标准输出
stylus src/main.styl

常用选项 #

选项 说明 示例
-o, --out 输出目录 stylus main.styl -o dist/
-w, --watch 监听文件变化 stylus -w main.styl
-c, --compress 压缩输出 stylus -c main.styl
-m, --sourcemap 生成 sourcemap stylus -m main.styl
-I, --include 添加导入路径 stylus -I ./lib main.styl
-u, --use 使用插件 stylus -u nib main.styl
--import 自动导入文件 stylus --import nib main.styl

完整示例 #

bash 
# 开发环境：监听 + sourcemap
stylus -w -m src/styles/main.styl -o dist/css/

# 生产环境：压缩
stylus -c src/styles/main.styl -o dist/css/

# 使用插件
stylus -u nib -c src/styles/main.styl -o dist/css/

# 添加导入路径
stylus -I ./src/styles/imports main.styl -o dist/

Node.js API 使用 #

基本用法 #

javascript 
const stylus = require('stylus');

const str = `
body
  font 14px/1.5 Helvetica, sans-serif
  color #333
`;

stylus.render(str, (err, css) => {
  if (err) throw err;
  console.log(css);
});

使用 API 配置 #

javascript 
const stylus = require('stylus');
const fs = require('fs');

const str = fs.readFileSync('main.styl', 'utf8');

stylus(str)
  .set('filename', 'main.styl')
  .set('compress', true)
  .set('sourcemap', true)
  .include('node_modules/nib')
  .render((err, css) => {
    if (err) throw err;
    fs.writeFileSync('main.css', css);
  });

API 方法 #

方法 说明
.set(key, value) 设置选项
.include(path) 添加导入路径
.import(path) 导入文件
.use(plugin) 使用插件
.define(name, value) 定义全局变量
.render(callback) 执行编译

构建工具集成 #

Webpack #

安装 loader：

bash 
npm install stylus stylus-loader --save-dev

配置 webpack.config.js：

javascript 
module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          'style-loader',
          'css-loader',
          'stylus-loader'
        ]
      }
    ]
  },
  resolve: {
    extensions: ['.js', '.styl']
  }
};

高级配置：

javascript 
module.exports = {
  module: {
    rules: [
      {
        test: /\.styl$/,
        use: [
          MiniCssExtractPlugin.loader,
          'css-loader',
          {
            loader: 'stylus-loader',
            options: {
              stylusOptions: {
                import: ['~nib'],
                use: [require('nib')()],
                compress: true
              }
            }
          }
        ]
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: '[name].[contenthash].css'
    })
  ]
};

Vite #

Vite 原生支持 Stylus，无需额外配置：

javascript 
// vite.config.js
export default {
  css: {
    preprocessorOptions: {
      stylus: {
        import: ['~nib/index.styl']
      }
    }
  }
}

在组件中使用：

vue 
<template>
  <div class="container">
    Hello Stylus!
  </div>
</template>

<style lang="stylus">
.container
  padding 20px
  background-color #f5f5f5
</style>

Gulp #

安装依赖：

bash 
npm install gulp gulp-stylus gulp-sourcemaps gulp-clean-css --save-dev

配置 gulpfile.js：

javascript 
const gulp = require('gulp');
const stylus = require('gulp-stylus');
const sourcemaps = require('gulp-sourcemaps');
const cleanCSS = require('gulp-clean-css');

gulp.task('styles', () => {
  return gulp.src('src/styles/*.styl')
    .pipe(sourcemaps.init())
    .pipe(stylus({
      compress: true,
      use: [require('nib')()]
    }))
    .pipe(cleanCSS())
    .pipe(sourcemaps.write('.'))
    .pipe(gulp.dest('dist/css'));
});

gulp.task('watch', () => {
  gulp.watch('src/styles/**/*.styl', gulp.series('styles'));
});

gulp.task('default', gulp.series('styles', 'watch'));

Rollup #

安装插件：

bash 
npm install rollup-plugin-stylus --save-dev

配置 rollup.config.js：

javascript 
import stylus from 'rollup-plugin-stylus';

export default {
  input: 'src/main.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife'
  },
  plugins: [
    stylus({
      output: 'dist/bundle.css',
      sourceMap: true
    })
  ]
};

编辑器配置 #

VS Code #

安装插件：

  1. language-stylus - Stylus 语法高亮和智能提示
  2. Stylus Supremacy - Stylus 格式化

配置 settings.json：

json 
{
  "stylusSupremacy.insertColons": false,
  "stylusSupremacy.insertSemicolons": false,
  "stylusSupremacy.insertBraces": false,
  "stylusSupremacy.sortProperties": "grouped",
  "stylusSupremacy.alwaysUseImport": true,
  "stylusSupremacy.quoteChar": "'"
}

WebStorm / IntelliJ IDEA #

WebStorm 内置 Stylus 支持，包括：

  • 语法高亮
  • 代码补全
  • 格式化
  • 文件监视器

配置 File Watcher：

  1. 打开 Preferences → Tools → File Watchers
  2. 添加 <custom> watcher
  3. 配置：
    • File type: Stylus
    • Program: stylus
    • Arguments: $FileName$ -o $FileDir$
    • Working directory: $FileDir$

项目结构推荐 #

text 
project/
├── src/
│   └── styles/
│       ├── variables.styl     # 变量定义
│       ├── mixins.styl        # 混入定义
│       ├── functions.styl     # 函数定义
│       ├── base/
│       │   ├── reset.styl     # 重置样式
│       │   └── typography.styl # 排版
│       ├── components/
│       │   ├── buttons.styl
│       │   ├── forms.styl
│       │   └── cards.styl
│       ├── layouts/
│       │   ├── header.styl
│       │   ├── footer.styl
│       │   └── sidebar.styl
│       ├── pages/
│       │   ├── home.styl
│       │   └── about.styl
│       └── main.styl          # 主入口
├── dist/
│   └── css/
│       └── main.css
└── package.json

常见问题 #

1. 找不到模块 #

bash 
Error: Cannot find module 'stylus'

解决：确保已安装 stylus：

bash 
npm install stylus --save-dev

2. 导入路径问题 #

stylus 
// 错误：找不到文件
@import 'mixins'

// 解决：使用相对路径或配置 include 路径
@import './mixins'

或在编译时添加路径：

bash 
stylus -I ./src/styles main.styl

3. 编码问题 #

确保文件使用 UTF-8 编码保存。

下一步 #

安装配置完成后，继续学习 基础语法 开始编写 Stylus 代码！

最后更新：2026-03-28