Lyda
489cc94316
- 使用 npm 全局安装 OpenCode，支持版本管理和自动更新 - 智能缓存策略：缓存 npm 目录和全局安装，加速后续构建 - 支持淘宝镜像源和自定义 npm 镜像，国内环境友好 - 版本检测：自动比对已安装版本，避免重复安装 - 输出安装版本、缓存命中状态和更新状态 - 提供详细的使用文档和多场景示例
319 lines
7.4 KiB
Markdown
319 lines
7.4 KiB
Markdown
# Setup OpenCode Action
|
||
|
||
使用 npm 全局安装 OpenCode 并缓存，支持版本检测和自动更新。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ **npm 安装**：使用 npm 全局安装，简单快速
|
||
- 🚀 **智能缓存**：缓存 npm 包和全局安装，加速后续构建
|
||
- 🔄 **自动更新**：版本变化时自动更新
|
||
- 🇨🇳 **国内镜像**：支持淘宝镜像源，国内环境友好
|
||
- ⚡ **快速恢复**：缓存命中时跳过安装，秒级完成
|
||
|
||
## 使用方法
|
||
|
||
### 基础用法
|
||
|
||
```yaml
|
||
- name: 安装 OpenCode
|
||
uses: ./.gitea/actions/setup-opencode
|
||
```
|
||
|
||
### 国内环境使用（推荐）
|
||
|
||
```yaml
|
||
- name: 安装 OpenCode（淘宝镜像）
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: 'latest'
|
||
use-taobao-registry: 'true'
|
||
```
|
||
|
||
### 指定版本
|
||
|
||
```yaml
|
||
- name: 安装 OpenCode 1.2.3
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: '1.2.3'
|
||
```
|
||
|
||
### 使用最新版本
|
||
|
||
```yaml
|
||
- name: 安装最新版 OpenCode
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: 'latest'
|
||
```
|
||
|
||
### 自定义 npm 包名
|
||
|
||
```yaml
|
||
- name: 安装自定义包
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
package-name: '@myorg/opencode'
|
||
version: '1.2.3'
|
||
```
|
||
|
||
### 自定义 npm 镜像源
|
||
|
||
```yaml
|
||
- name: 使用自定义镜像源
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: 'latest'
|
||
npm-registry: 'https://registry.npmmirror.com'
|
||
```
|
||
|
||
### 强制重新安装
|
||
|
||
```yaml
|
||
- name: 强制重新安装 OpenCode
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: '1.2.3'
|
||
skip-cache: 'true'
|
||
```
|
||
|
||
### 使用输出
|
||
|
||
```yaml
|
||
- name: 安装 OpenCode
|
||
id: setup-opencode
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: 'latest'
|
||
|
||
- name: 显示版本信息
|
||
run: |
|
||
echo "安装版本: ${{ steps.setup-opencode.outputs.version }}"
|
||
echo "缓存命中: ${{ steps.setup-opencode.outputs.cache-hit }}"
|
||
echo "执行更新: ${{ steps.setup-opencode.outputs.updated }}"
|
||
|
||
- name: 使用 OpenCode
|
||
run: |
|
||
opencode --version
|
||
opencode build
|
||
```
|
||
|
||
## 输入参数
|
||
|
||
| 参数 | 描述 | 必填 | 默认值 |
|
||
| ---- | ---- | ---- | ------ |
|
||
| `version` | OpenCode 版本号（例如: 1.0.0, latest） | 否 | `latest` |
|
||
| `package-name` | npm 包名 | 否 | `opencode` |
|
||
| `use-taobao-registry` | 使用淘宝 npm 镜像源 (true/false) | 否 | `false` |
|
||
| `npm-registry` | 自定义 npm 镜像源地址 | 否 | `` |
|
||
| `cache-prefix` | 缓存前缀名称 | 否 | `opencode-npm` |
|
||
| `skip-cache` | 跳过缓存，强制重新安装 (true/false) | 否 | `false` |
|
||
|
||
## 输出
|
||
|
||
| 输出 | 描述 |
|
||
| ---- | ---- |
|
||
| `version` | 安装的 OpenCode 版本 |
|
||
| `cache-hit` | 缓存是否命中 (true/false) |
|
||
| `updated` | 是否执行了更新 (true/false) |
|
||
|
||
## 工作原理
|
||
|
||
1. **参数验证**：验证输入参数的有效性
|
||
2. **配置镜像源**：根据配置设置 npm 镜像源（支持淘宝镜像）
|
||
3. **缓存检查**：根据包名和版本生成缓存键，尝试恢复缓存
|
||
4. **版本比对**：
|
||
- 检查已安装版本是否与请求版本一致
|
||
- 版本一致：跳过安装
|
||
- 版本不一致或未安装：执行 npm 安装
|
||
5. **npm 安装**：使用 `npm install -g` 全局安装指定版本
|
||
6. **保存缓存**：缓存 npm 包和全局安装目录
|
||
|
||
## 缓存策略
|
||
|
||
- **缓存内容**：
|
||
- `~/.npm` - npm 缓存目录
|
||
- `/usr/local/lib/node_modules/{package}` - 全局安装的包
|
||
- `/usr/local/bin/{package}` - 全局命令
|
||
- **缓存键格式**：`{OS}-{cache-prefix}-{package-name}-{version}`
|
||
- **缓存更新**：版本号变化时自动更新缓存
|
||
- **缓存生命周期**：遵循 GitHub Actions 缓存默认生命周期（最多 7 天未使用）
|
||
|
||
## 完整示例
|
||
|
||
### 示例 1：基础 CI/CD 流程
|
||
|
||
```yaml
|
||
name: Build with OpenCode
|
||
|
||
on:
|
||
push:
|
||
branches: [ main ]
|
||
|
||
jobs:
|
||
build:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- name: 检出代码
|
||
uses: actions/checkout@v4
|
||
|
||
- name: 安装 OpenCode
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: '1.2.3'
|
||
|
||
- name: 构建项目
|
||
run: |
|
||
opencode build --release
|
||
|
||
- name: 运行测试
|
||
run: |
|
||
opencode test
|
||
```
|
||
|
||
### 示例 2：国内环境使用
|
||
|
||
```yaml
|
||
name: Build in China
|
||
|
||
on: [push]
|
||
|
||
jobs:
|
||
build:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: 安装 OpenCode（淘宝镜像）
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: 'latest'
|
||
use-taobao-registry: 'true'
|
||
|
||
- name: 构建
|
||
run: opencode build
|
||
```
|
||
|
||
### 示例 3：多版本测试
|
||
|
||
```yaml
|
||
name: Test Multiple Versions
|
||
|
||
on: [push]
|
||
|
||
jobs:
|
||
test:
|
||
runs-on: ubuntu-latest
|
||
strategy:
|
||
matrix:
|
||
opencode-version: ['1.0.0', '1.1.0', '1.2.0', 'latest']
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: 安装 OpenCode ${{ matrix.opencode-version }}
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: ${{ matrix.opencode-version }}
|
||
|
||
- name: 运行测试
|
||
run: |
|
||
echo "Testing with OpenCode ${{ matrix.opencode-version }}"
|
||
opencode --version
|
||
opencode test
|
||
```
|
||
|
||
### 示例 4：带缓存状态检查
|
||
|
||
```yaml
|
||
name: Build with Cache Info
|
||
|
||
on: [push]
|
||
|
||
jobs:
|
||
build:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: 安装 OpenCode
|
||
id: opencode
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: 'latest'
|
||
use-taobao-registry: 'true'
|
||
|
||
- name: 显示缓存状态
|
||
run: |
|
||
if [[ "${{ steps.opencode.outputs.cache-hit }}" == "true" ]]; then
|
||
echo "✅ 使用缓存，节省时间！"
|
||
else
|
||
echo "📥 首次安装或版本更新"
|
||
fi
|
||
|
||
if [[ "${{ steps.opencode.outputs.updated }}" == "true" ]]; then
|
||
echo "🔄 OpenCode 已更新到 ${{ steps.opencode.outputs.version }}"
|
||
fi
|
||
|
||
- name: 构建
|
||
run: opencode build
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **国内环境**：🇨🇳 在国内使用时，强烈建议设置 `use-taobao-registry: 'true'` 使用淘宝镜像源
|
||
2. **版本格式**：版本号应遵循语义化版本规范（如 1.2.3）
|
||
3. **npm 环境**：需要 Node.js 和 npm 已安装（GitHub Actions 默认已安装）
|
||
4. **全局安装**：使用 `npm install -g` 全局安装，命令自动添加到 PATH
|
||
5. **缓存限制**：GitHub Actions 缓存有大小限制（10GB）
|
||
|
||
## 故障排查
|
||
|
||
### 国内网络问题
|
||
|
||
```yaml
|
||
- name: 使用淘宝镜像源
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: '1.2.3'
|
||
use-taobao-registry: 'true'
|
||
```
|
||
|
||
### 自定义镜像源
|
||
|
||
```yaml
|
||
- name: 使用自定义镜像
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: '1.2.3'
|
||
npm-registry: 'https://registry.npmmirror.com'
|
||
```
|
||
|
||
### 安装失败
|
||
|
||
```yaml
|
||
- name: 清除缓存重新安装
|
||
uses: ./.gitea/actions/setup-opencode
|
||
with:
|
||
version: '1.2.3'
|
||
skip-cache: 'true'
|
||
```
|
||
|
||
### 版本不匹配
|
||
|
||
检查 `updated` 输出，如果为 `true` 表示已更新到新版本。
|
||
|
||
## 优势
|
||
|
||
相比二进制安装方式，npm 安装具有以下优势：
|
||
|
||
- ✅ **简单直接**：一条 `npm install -g` 命令搞定
|
||
- ✅ **依赖管理**：npm 自动处理依赖关系
|
||
- ✅ **版本管理**：npm 原生支持版本管理
|
||
- ✅ **跨平台**：npm 包通常支持多平台
|
||
- ✅ **更新方便**：版本更新只需修改版本号
|
||
- ✅ **缓存高效**：缓存 npm 目录和全局安装，恢复快速
|
||
|
||
## 许可证
|
||
|
||
与主仓库保持一致。
|