sapui5-linter

SAPUI5 Linter 技能

相关技能

• sap-dependency-security：在强化 UI5 lint 工具链升级的依赖管理，以及插件／工具链锁文件控制时使用

何时使用此技能

在添加或运行 @ui5/linter、配置 UI5 lint 规则、准备迁移到 UI5 2.x、自动修复已弃用的 API／全局变量／清单问题、生成 CI 报告，或排查 ui5lint 的解析、性能或配置行为时，请使用此技能。

目录

• 概述
• 快速入门
• 配置
• CLI 用法
• 捆绑资源

概述

UI5 Linter（@ui5/linter）是一款专为 SAPUI5 和 OpenUI5 项目设计的静态代码分析工具。它可帮助开发者在升级到 UI5 2.x 之前，识别兼容性问题、已弃用的 API、安全问题和不符合最佳实践的用法。

主要功能：

• ✅ 检测 19 类问题，包括已弃用的 API、全局变量用法和 CSP 违规
• ✅ 自动修复常见问题（no-globals、no-deprecated-api、清单属性）
• ✅ 支持 JavaScript、TypeScript、XML、JSON、HTML 和 YAML 文件
• ✅ 可配置忽略模式和目标文件
• ✅ 支持多种输出格式：stylish、JSON、Markdown、HTML
• ✅ 性能出色：耗时 1–40 秒，具体取决于项目大小

当前版本：1.22.0（于 2026-06-14 通过 npm 验证） 官方代码库：https://github.com/UI5/linter

---

快速入门

前提条件

Node.js：v20.11.x、v22.0.0 或更高版本 npm：v8.0.0 或更高版本

验证前提条件：

node --version  # Should be v20.11+ or v22+
npm --version   # Should be v8+

安装

全局安装（推荐用于 CLI）：

npm install --global @ui5/linter

本地安装（推荐用于项目集成）：

npm install --save-dev @ui5/linter

验证安装：

ui5lint --version  # Should output: 1.22.0 or higher

基本用法

从项目根目录运行 linter：

# Lint entire project
ui5lint

# Lint specific files or directories
ui5lint "webapp/**/*.js"
ui5lint "webapp/controller/" "webapp/view/"

# Show detailed information about findings
ui5lint --details

常见工作流

开发工作流：

# 1. Check for issues with details
ui5lint --details

# 2. Preview automatic fixes
UI5LINT_FIX_DRY_RUN=true ui5lint --fix

# 3. Apply fixes
ui5lint --fix

# 4. Review changes
git diff

# 5. Verify fixes worked
ui5lint --details

配置

配置文件设置

创建 ui5lint.config.{js|mjs|cjs}：

module.exports = {
  rules: {
    // Recommended rules
    "no-deprecated-api": "error",
    "no-globals": "error",
    "no-ambiguous-event-handler": "error",
    "no-outdated-manifest-version": "error"
  },
  exclude: [
    "dist/**",
    "node_modules/**",
    "test/**/*.{spec,js,ts}"
  ]
};

常见配置模式

// Strict for production, relaxed for development
const isProduction = process.env.NODE_ENV === 'production';

module.exports = {
  rules: {
    "no-deprecated-api": isProduction ? "error" : "warn",
    "no-globals": isProduction ? "error" : "warn"
  },
  exclude: [
    "legacy/**/*",
    "**/*.min.js"
  ]
};

CLI 用法

基本命令

# Basic linting
ui5lint

# With detailed output
ui5lint --details

# Fix auto-fixable issues
ui5lint --fix

# JSON output for CI/CD
ui5lint --format json

# HTML report for documentation
ui5lint --format html --details

# Performance monitoring
ui5lint --perf

Lint 规则概述

异步与现代模式

• async-component-flags：验证异步组件配置
• prefer-test-starter：验证 Test Starter 实现

安全

• csp-unsafe-inline-script：检测不安全的内联脚本

事件处理程序

• no-ambiguous-event-handler：确保事件处理程序的表示法正确 ✅ 可自动修复

弃用检测（7 条规则）

• no-deprecated-api：检测已弃用的 API ✅
• no-deprecated-component：查找已弃用的组件依赖项
• no-deprecated-control-renderer：验证控件渲染器模式
• no-deprecated-library：检查清单中已弃用的库

全局变量用法

• no-globals：识别全局变量用法 ✅ 可自动修复
• no-implicit-globals：检测隐式全局访问

错误报告

• parsing-error：报告语法／解析错误
• autofix-error：报告自动修复失败

API 用法

• ui5-class-declaration：验证 UI5 类声明模式（TypeScript）
• unsupported-api-usage：确保 API 用法正确

清单现代化（3 条规则）

• no-outdated-manifest-version：要求使用 Manifest Version 2
• no-removed-manifest-property：识别不兼容的属性 ✅ 可自动修复

完整规则参考**：请参阅 references/rules-complete.md

与开发工作流集成

package.json 脚本

{
  "scripts": {
    "lint": "ui5lint",
    "lint:fix": "ui5lint --fix",
    "lint:details": "ui5lint --details",
    "lint:ci": "ui5lint --quiet --format json > lint-results.json",
    "lint:report": "ui5lint --format html --details > lint-report.html"
  },
  "devDependencies": {
    "@ui5/linter": "^1.22.0"
  }
}

常见场景

场景 1：新建 UI5 项目

1. 安装 linter
2. 创建配置（使用模板）
3. 将 npm 脚本添加到 package.json
4. 运行初始 lint
5. 修复可自动修复的问题
6. 检查剩余问题

场景 2：准备迁移到 UI5 2.x

1. 运行 linter 查找所有问题
2. 优先处理严重问题
3. 应用自动修复
4. 查看自动修复限制文档
5. 手动修复不受支持的 API
6. 处理 Core API 问题（#619、#620）
7. 将 manifest 更新为 v2
8. 修复 no-outdated-manifest-version、no-removed-manifest-property 问题
9. 确认所有问题均已解决

故障排除

常见问题

症状：Linter 报告解析错误 解决方案：检查配置文件是否存在语法错误

症状：自动修复不起作用 解决方案：查看 references/autofix-complete.md 中的自动修复限制

症状：大型代码库出现性能问题 解决方案：添加忽略模式，使用针对性 lint

已知限制

• 无法将同步模式转换为异步模式
• Core/Configuration API 的自动修复能力有限（约 50 个 API）
• 对 jQuery.sap API 的支持仅限于基本方法
• 不会自动发现 Node.js 模块

最佳实践

1. 尽早并经常运行 Linter

• 添加 pre-commit 钩子，即时获取反馈
• 参见 templates/husky-pre-commit.template

2. 使用配置文件保存持久设置

• 特定于环境的配置
• 项目范围的忽略模式

3. 逐步修复问题

1. 先修复错误
2. 再修复警告
3. 每次修复后都进行审查和测试

4. 记录已抑制的规则

• 说明团队级抑制规则的原因
• 谨慎使用，并提供明确的理由

5. 集成到 CI/CD

• 错误导致构建失败，警告不影响构建
• 为相关方生成报告

6. 监控性能

• 长期跟踪 lint 性能

---

参考文档

外部资源

• 官方代码仓库：https://github.com/UI5/linter
• 问题报告：https://github.com/UI5/linter/issues
• 讨论：https://github.com/UI5/linter/discussions
• 聊天支持：https://discord.gg/sapui5
• SAP 社区：https://community.sap.com/tags/ui5

详细文档

• 完整规则参考：references/rules-complete.md
• 自动修复能力：references/autofix-complete.md
• 性能指南：references/performance.md
• 故障排除指南：references/support-and-community.md
• 贡献指南：references/contributing.md

模板

• 配置模板：templates/ui5lint.config.mjs
• package.json 模板：templates/package.json.template
• Husky Pre-commit：templates/husky-pre-commit.template

支持与更新

• 版本：1.22.0（当前版本）
• 发行说明：可在 GitHub 发行版本中查看
• 路线图：记录在 GitHub Issues 和 Discussions 中
• 电子邮件：[email protected]
• 社区：Discord #sapui5 频道

随附资源

参考文档

• references/rules-complete.md - 全部 19 条 lint 规则的完整参考
• references/autofix-complete.md - 自动修复能力和限制的详细说明
• references/performance.md - 性能优化指南
• references/support-and-community.md - 支持渠道和社区资源
• references/contributing.md - 贡献指南

模板

• templates/ui5lint.config.mjs - 配置模板
• templates/package.json.template - Package.json 模板
• templates/husky-pre-commit.template - Pre-commit 钩子模板

---

最后更新：2026-06-14 | 版本：2.4.1 上一个重构版本：1.0.1 | 减少行数：376（从 827 行减少） 下次审查：2026-02-25