megalinter-setup

MegaLinter 设置

在当前仓库中安装或升级 MegaLinter。**始终使用 npx mega-linter-runner 来搭建或升级配置，切勿从头编写 .mega-linter.yml 或 CI 工作流文件。**之后只能对生成的文件进行微调。

自定义 flavor 仓库：仅当用户明确要求创建或维护自定义 MegaLinter flavor（即只包含所需 linter、并从专用的 megalinter-custom-flavor-* 仓库发布的自有镜像）时，这才属于与下方安装流程不同的任务：请从此技能目录加载 custom-flavor.md 并按其说明操作。本页其他内容均针对使用 MegaLinter 的项目。

1. 分析仓库

收集所需信息，以便回答安装程序的问题：

• Flavor：检测主要技术，并选择一个 flavor（python、javascript、java、go、php、ruby、rust、salesforce、swift、terraform、dotnet、dotnetweb、c_cpp、documentation、formatters、security 等）。技术混杂或无法明确判断时，选择 all。
• CI 系统：根据现有配置判断（.github/ → gitHubActions、.gitlab-ci.yml → gitLabCI、azure-pipelines.yml → azure、bitbucket-pipelines.yml → bitbucket、Jenkinsfile → jenkins、.drone.yml → droneCI），或根据 Git 远程主机判断。都没有时，选择 other。
• 默认分支：使用 git remote show origin 确定，或使用当前仓库的默认分支。

2. 安装或升级

尚未配置 MegaLinter — 以非交互方式运行安装程序：

npx mega-linter-runner --install --no-prompt \
  --flavor <flavor> \
  --setup-ci <ci> \
  --setup-default-branch <branch> \
  --fix

如果运行器拒绝了上述某个选项（报错“Invalid option”），说明解析到的 mega-linter-runner 版本已过时：请使用 npx mega-linter-runner@latest 重新运行（--setup-* 和 --linter 选项需要较新的版本）。

注意：

• 默认情况下，每次运行都会验证整个代码库。只有用户明确要求仅检查更新过的文件时，才传入 --setup-validate-all-code-base diff。
• 只有用户要求使用 beta 版本时，才添加 --release beta（安装程序随后会在 .mega-linter.yml 中写入 MEGALINTER_VERSION: beta）。
• 版本规则（适用于所有技能）：运行器和 Docker 镜像版本始终遵循 .mega-linter.yml 中的 MEGALINTER_VERSION — 如果值为 beta，则调用 npx mega-linter-runner@beta；其他情况下调用普通的 npx mega-linter-runner，且除本安装步骤外，绝不传入 --release。
• --fix 会启用自动修复（APPLY_FIXES: all）；如果用户不想要自动格式化，则省略此选项。
• 如果用户在场并希望交互式选择，则改为运行普通的 npx mega-linter-runner --install，让用户自行回答。

保留现有自定义配置。 在非交互模式下，安装程序会覆盖冲突文件，但会先将每个已有目标文件（配置文件和 CI 工作流文件）备份为 <file>.megalinter-setup.bak。安装后：

1. 将每个 .megalinter-setup.bak 文件与重新生成的版本进行比较。
2. 重新应用仍然适用的用户自定义配置（额外的工作流步骤、环境变量、自定义触发器、新增的配置项等）。如果某项自定义配置与新模板冲突，或其意图不明确，请询问用户要保留哪些内容。
3. 合并完成后，删除 .megalinter-setup.bak 文件。

配置已存在 — 升级配置：

npx mega-linter-runner --upgrade --no-prompt

--upgrade 会将仓库中的所有 MegaLinter 引用迁移到当前主版本：CI 工作流文件中的镜像标签和 Action 版本、已弃用的变量名称，以及 .mega-linter.yml 的 MEGALINTER_VERSION 属性。只要仓库引用了较旧的 MegaLinter 主版本（例如 v8 镜像标签），就应运行此命令，即使用户只要求进行“检查”。

运行 --upgrade 后必须执行 — 将 Docker 镜像引用迁移到 ghcr.io。 从 MegaLinter v9.5.0 起，镜像仅发布到 GitHub Container Registry（Docker Hub 上的版本冻结在 v9.4.0），且 --upgrade 不会重写镜像仓库地址：它只会将引用规范化为裸的 oxsecurity/megalinter... 形式。因此，始终要完成以下步骤：

1. 搜索仓库中的所有 CI/工作流文件（.github/workflows/*、.gitlab-ci.yml、azure-pipelines.yml、bitbucket-pipelines.yml、Jenkinsfile、.drone.yml、shell 脚本等），查找 oxsecurity/megalinter。
2. 将所有用作 Docker 镜像 的引用（出现在 image:、container:、services:、docker run、docker pull 后，或任何 oxsecurity/megalinter[-<flavor>]:<tag> 形式的引用，包括独立的 megalinter-only-* 镜像和带有 docker.io/ 前缀的引用）改写为添加 ghcr.io/ 前缀的相同引用 — 保留 flavor 和标签不变：oxsecurity/megalinter-python:v10 改为 ghcr.io/oxsecurity/megalinter-python:v10。
3. 不要更改：已有 ghcr.io/ 前缀的引用、GitHub Action 引用（uses: oxsecurity/megalinter@... — Action 不是 Docker 镜像）以及文档 URL。

同时升级 MegaLinter 技能和子 Agent

仓库配置只是设置的一部分。你正在使用的 MegaLinter 技能及其安装的子 Agent 定义，在添加时会复制到项目中（或用户配置文件中），不会自动更新——因此，即使升级了仓库，仍可能依据旧版 MegaLinter 的指南运行。每次升级时，以及用户要求更新 MegaLinter 技能时，都要刷新它们。

首先确定 MegaLinter 的安装方式，因为两种安装模式的更新方式不同。命名空间不是可靠的判断依据：只有部分平台会在插件技能前加上插件名称（megalinter:megalinter-setup），而且没有平台能查询技能的来源。请根据文件系统判断；如果仍无法确定，就询问用户：

仓库或用户配置文件中的依据	安装模式
平台的 plugins/ 目录下有 MegaLinter 插件文件夹（megalinter）	插件
.claude/skills/megalinter*、.github/skills/megalinter*、.agents/skills/megalinter*，或用户配置文件下存在相同路径	技能
两者都没有，或两者都有	询问用户

如果它是作为 Agent 插件安装的，skills CLI 不会管理它：改为更新插件，并跳过本节其余内容——子 Agent 会随插件一起刷新。

平台	更新命令
Claude Code	/plugin update megalinter@megalinter
Cursor	Customize → Plugins，然后更新 MegaLinter
GitHub Copilot	copilot plugin install megalinter@megalinter
Codex	codex plugin marketplace upgrade megalinter
Gemini CLI / Antigravity	gemini extensions update megalinter

否则，请检查它们的安装方式：

npx skills list

MegaLinter 条目会显示安装路径和 Source。local 来源表示这些文件不由 skills CLI 管理（例如 MegaLinter 仓库自身的 skills/ 文件夹，或手动复制的文件）：不要改动它们，并告知用户。

否则，请明确指定技能名称进行更新——仅运行 npx skills update 还会更新项目中安装的所有其他无关技能：

npx skills update megalinter megalinter-setup megalinter-check megalinter-fix -y

如果项目级和用户级技能同时存在，而只需更新其中一类，请添加 -p 将范围限定为项目级技能，或添加 -g 将范围限定为用户级技能。

如果更新提示没有需要处理的内容（通过 --copy 添加的技能不一定会被跟踪），请改为重新运行安装命令——它会用当前版本覆盖已安装的副本：

npx skills add oxsecurity/megalinter/skills -s '*' -a <agent> -y

然后刷新子 Agent：skills update 只会重写技能文件夹，不会更新复制到平台 Agent 文件夹中的副本（.claude/agents/、.opencode/agent/、.github/agents/）。请为这三个定义重新执行下方步骤 4，使其与已刷新的技能保持一致；覆盖用户自定义的定义前，先征求用户同意。

最后请注意，你当前正在执行的技能可能刚刚已被重写。刷新后，请重新读取此技能目录下的 SKILL.md；如果其中的说明与已加载的内容不同，请按更新后的说明继续。

3. 优化 .mega-linter.yml（仅在安装/升级后）

运行器生成/升级文件后，你可以调整 .mega-linter.yml：

• 确保已设置 MEGALINTER_FLAVOR 和 MEGALINTER_VERSION（安装程序会写入它们；如果升级较旧的配置，请添加它们）——它们决定 mega-linter-runner 和这些技能使用哪个 Docker 镜像。
• 添加用户要求的 DISABLE / DISABLE_LINTERS 条目。
• 为生成的或供应商提供的文件夹添加 FILTER_REGEX_EXCLUDE（例如 (dist/|build/|vendor/|node_modules/)）。排除的目录（以及通过这些正则表达式识别出的文件夹）也会通过原生排除参数或生成的忽略/配置文件，自动传递给项目模式的 Linter；如果仓库已维护某个 Linter 自己的最新忽略/配置文件，则可通过 FORWARD_EXCLUDED_DIRECTORIES: false（全局）或 <LINTER_KEY>_FORWARD_EXCLUDED_DIRECTORIES: false（针对单个 Linter）关闭此传递功能。

根据其 JSON schema 验证文件：https://raw.githubusercontent.com/oxsecurity/megalinter/main/megalinter/descriptors/schemas/megalinter-configuration.jsonschema.json

4. 安装或刷新 MegaLinter 子 Agent（如果你的平台支持）

此技能在 agents/ 文件夹中附带三个子 Agent 定义（megalinter-watcher、megalinter-runner、megalinter-fixer），它们可以将 CI 日志和 Linter 输出留在主上下文之外，从而加快其他 MegaLinter 技能的运行并降低成本。

如果 MegaLinter 是作为 Agent 插件安装的，请跳过整个步骤：插件已附带这三个定义（为 Claude Code 和 Cursor 声明，并以 com.github.copilot/agents/*.agent.md 的形式提供给 Copilot 客户端）。再次复制会安装第二套定义，并在下次插件更新时造成版本不一致。

跳过前请确认：检查你可用的 Agent 列表中是否确实包含这三个 Agent，名称可以是带命名空间的（megalinter:megalinter-watcher），也可以是不带命名空间的（megalinter-watcher）。如果列表中没有这些 Agent，平台可能无法加载插件中的 Agent；请告知用户，并按照下文说明从 agents/ 安装。

如果你所使用的编码 Agent 支持自定义子 Agent 定义（Claude Code、OpenCode、GitHub Copilot、Codex……你知道自己是否支持），请阅读此技能目录中的 agents/INSTALL.md，并按照对应平台的说明操作：将三个 agents/*.md 文件复制到平台的 Agent 文件夹，并在需要时调整文件名和 frontmatter。特别注意，Copilot 要求在 .github/agents/ 中使用 .agent.md 后缀，并且不接受 model: haiku 覆盖设置。

如果目标文件已存在，请在覆盖前询问用户。升级模式下，现有文件正是需要替换的文件：向用户展示更改内容，并在重新应用新版本时保留他们所做的自定义设置（例如模型覆盖或调整后的 tools 列表）。如果你的平台不支持子 Agent，请跳过此步骤——这些技能可以正常回退为内联执行。

5. 可观测性仪表板（可选）

MegaLinter 可以将结果发送到可观测性平台（Grafana、Datadog、Elastic、New Relic），并提供开箱即用的仪表板：质量门禁、错误趋势、跨仓库的热门规则和文件。文档：https://megalinter.io/latest/observability/

只有当用户似乎对监控感兴趣，或已经在使用其中一个平台时，才向用户提供此选项。如果用户接受：

1. 询问他们使用哪个提供商，并确认提供商的身份验证环境变量已就绪（绝不要将密钥写入已提交的文件）：
   • grafana：GRAFANA_URL + GRAFANA_TOKEN（服务账号令牌）
   • datadog：DD_SITE + DD_API_KEY + DD_APP_KEY（或 DD_BEARER_TOKEN）
   • elastic：KIBANA_URL + ELASTIC_API_KEY
   • newrelic：NEW_RELIC_API_KEY + NEW_RELIC_ACCOUNT_ID + NEW_RELIC_REGION
2. 配置仪表板：npx mega-linter-runner --upload-dashboards <provider>（幂等操作，可随时重新运行以刷新）。
3. 在 .mega-linter.yml 中添加：API_REPORTER: true、API_REPORTER_PROVIDER: <provider>，以及提供商的非机密变量（端点、站点、区域——参见该提供商的文档页面）。提醒用户在 CI 密钥中设置身份验证变量（API_REPORTER_* 令牌/密钥）。

6. 收尾

• 向用户展示生成或更新的文件。
• 提供两种体验 MegaLinter 的方式（首次安装和升级均适用），并主动询问是否由你代为操作。本地运行会消耗大量资源（基于 Docker，首次运行时会下载数 GB 的映像，之后会占用 CPU、RAM 和磁盘），因此通常建议在 CI 中运行——询问用户希望选择哪种方式（如果平台提供结构化提问机制，请优先推荐 CI 选项），不要擅自替用户决定：
  • 创建拉取请求（推荐），包含生成或更新的文件（如果当前分支已经是功能分支，则提交到当前分支；否则创建新分支——绝不要提交到默认分支——然后推送并打开 PR），随后在创建的 PR 上运行 megalinter-check 技能（监视模式），关注 CI 作业的结果并修复错误。
  • 在本地运行 MegaLinter，通过 megalinter-check 技能（本地模式）在推送任何内容之前预览并修复错误。首次运行时会先进行预运行分析（--prerun，MegaLinter v10 或 beta），建议调整 .mega-linter.yml 的性能（要排除的目录、flavor），然后再进行实际的 lint。
• 未经用户确认，不要提交或推送；也绝不要在默认分支上提交或推送。