2025 TypeScript Action 开发指南：从模板到发布全流程
项目地址: https://gitcode.com/gh_mirrors/ty/typescript-action 你是否还在为手动配置 GitHub Action 而头疼？面对复杂的 CI/CD 流程束手无策？本文将带你使用 typescript-action 模板，从零构建专业、可测试、易维护的自动化工作流，让你的开发效率提升 10 倍！
读完本文，你将掌握：
- TypeScript Action 项目的标准化搭建流程
- 自动化测试、 linting 与构建的最佳实践
- 从本地调试到全球发布的完整工作流
- 版本管理与依赖维护的核心技巧
项目概述：为什么选择 typescript-action？
typescript-action 是一个功能完备的 GitHub Action 开发模板，它提供了从编码到发布的全流程支持。该项目基于 TypeScript 构建，集成了测试框架、代码检查工具和自动化部署流程，让开发者能够专注于业务逻辑而非繁琐的配置工作。
核心优势
| 特性 | 传统手动配置 | typescript-action 模板 |
|---|---|---|
| 开发语言 | JavaScript | TypeScript（类型安全） |
| 测试支持 | 需手动集成 | 内置 Jest 测试框架 |
| 构建工具 | 无 | Rollup 自动打包 |
| 工作流配置 | 从零编写 | 预置 CI/CD 流程 |
| 版本管理 | 手动操作 | 自动化版本控制脚本 |
| 代码质量 | 无保障 | ESLint + Prettier 强制规范 |
项目架构
快速开始：5 分钟搭建开发环境
环境准备
在开始之前，请确保你的开发环境满足以下要求：
- Node.js 24.0.0 或更高版本
- Git
- npm 或 yarn 包管理器
安装步骤
- 克隆仓库
git clone https://gitcode.com/gh_mirrors/ty/typescript-action.git
cd typescript-action
- 安装依赖
npm install
- 构建项目
npm run build
- 运行测试
npm test
- 本地调试
npx @github/local-action . src/main.ts .env
核心功能解析
1. TypeScript 集成
项目使用 TypeScript 作为开发语言，提供了类型安全保障。核心源代码位于 src/ 目录下，主要包括：
src/index.ts: 入口文件src/main.ts: 核心逻辑实现src/wait.ts: 工具函数
// src/main.ts 核心代码示例
import * as core from '@actions/core'
import { wait } from './wait.js'
export async function run(): Promise<void> {
try {
const ms: string = core.getInput('milliseconds')
core.debug(`Waiting ${ms} milliseconds ...`)
await wait(parseInt(ms, 10))
core.setOutput('time', new Date().toTimeString())
} catch (error) {
if (error instanceof Error) core.setFailed(error.message)
}
}
2. 构建系统
项目使用 Rollup 作为构建工具，配置文件 rollup.config.ts 定义了输入输出、模块解析和代码转换规则：
// rollup.config.ts
import typescript from '@rollup/plugin-typescript'
import nodeResolve from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'
export default {
input: 'src/index.ts',
output: {
file: 'dist/index.js',
format: 'es',
sourcemap: true
},
plugins: [typescript(), nodeResolve(), commonjs()]
}
3. 测试框架
项目使用 Jest 作为测试框架，测试文件位于 __tests__/ 目录下：
// __tests__/main.test.ts 示例
import { jest } from '@jest/globals'
import * as core from '../__fixtures__/core.js'
import { wait } from '../__fixtures__/wait.js'
import { run } from '../src/main.js'
describe('main.ts', () => {
beforeEach(() => {
core.getInput.mockImplementation(() => '500')
wait.mockImplementation(() => Promise.resolve('done!'))
})
it('Sets the time output', async () => {
await run()
expect(core.setOutput).toHaveBeenCalledWith(
'time',
expect.stringMatching(/^\d{2}:\d{2}:\d{2}/)
)
})
})
高级配置：定制你的 Action
1. action.yml 配置详解
action.yml 文件定义了 Action 的元数据，包括名称、描述、输入输出参数等：
name: 'TypeScript Action'
description: 'Create a TypeScript Action with tests, linting, and more'
author: 'Your Name'
branding:
icon: 'code'
color: 'blue'
inputs:
milliseconds:
description: 'Waiting time in milliseconds'
required: true
default: '1000'
outputs:
time:
description: 'Current time after waiting'
runs:
using: 'node24'
main: 'dist/index.js'
2. 自定义工作流
项目提供了多个预置的 GitHub 工作流配置，位于 .github/workflows/ 目录下，包括：
ci.yml: 持续集成流程linter.yml: 代码检查check-dist.yml: 构建产物检查codeql-analysis.yml: 代码安全分析
你可以根据需要修改这些配置文件，或创建新的工作流。
测试与调试最佳实践
1. 单元测试
使用 Jest 编写单元测试，测试文件放在 __tests__/ 目录下。运行测试命令：
npm test
生成测试覆盖率报告：
npm run coverage
2. 本地调试
使用 @github/local-action 工具在本地调试 Action：
npx @github/local-action . src/main.ts .env
创建 .env 文件设置环境变量：
INPUT_MILLISECONDS=500
GITHUB_WORKSPACE=/path/to/workspace
3. 集成测试
在实际 GitHub 环境中测试 Action，可以创建一个测试仓库，引用本地 Action：
steps:
- uses: actions/checkout@v4
- uses: ./typescript-action
with:
milliseconds: 1000
发布与版本管理
1. 版本控制策略
项目采用语义化版本（SemVer）规范，版本号格式为 vX.Y.Z：
- X: 主版本号（不兼容的 API 变更）
- Y: 次版本号（向后兼容的功能新增）
- Z: 修订号（向后兼容的问题修复）
2. 发布流程
使用项目提供的发布脚本：
script/release
该脚本会引导你完成以下步骤：
- 获取最新版本号
- 输入新版本号
- 创建版本标签
- 推送标签到远程仓库
3. 发布到 GitHub Marketplace
- 在 GitHub 仓库页面点击 "Releases" -> "Draft a new release"
- 选择或创建标签
- 填写发布说明
- 勾选 "Publish this Action to the GitHub Marketplace"
- 点击 "Publish release"
实战案例：构建你的第一个 TypeScript Action
场景：自动生成 CHANGELOG
假设你需要创建一个 Action，在每次发布时自动生成 CHANGELOG 文件。
步骤 1: 创建新项目
git clone https://gitcode.com/gh_mirrors/ty/typescript-action.git changelog-action
cd changelog-action
步骤 2: 修改 action.yml
name: 'Generate CHANGELOG'
description: 'Automatically generate CHANGELOG.md from git commits'
inputs:
github-token:
description: 'GitHub access token'
required: true
outputs:
changelog:
description: 'Generated changelog content'
步骤 3: 实现核心逻辑
修改 src/main.ts:
import * as core from '@actions/core'
import { Octokit } from '@octokit/rest'
export async function run(): Promise<void> {
try {
const githubToken = core.getInput('github-token')
const octokit = new Octokit({ auth: githubToken })
// 获取 commits 历史
const { data: commits } = await octokit.rest.repos.listCommits({
owner: core.getInput('owner'),
repo: core.getInput('repo'),
})
// 生成 changelog 内容
const changelog = generateChangelog(commits)
core.setOutput('changelog', changelog)
core.setOutput('time', new Date().toTimeString())
} catch (error) {
if (error instanceof Error) core.setFailed(error.message)
}
}
function generateChangelog(commits: any[]): string {
let changelog = '# CHANGELOG\n\n'
commits.forEach(commit => {
changelog += `- ${commit.commit.message}\n`
})
return changelog
}
run()
步骤 4: 添加依赖
npm install @octokit/rest
步骤 5: 构建与测试
npm run all
npm test
步骤 6: 发布 Action
script/release
常见问题与解决方案
Q1: Action 运行时报错 "Module not found"
A: 确保已运行 npm run package 命令，生成包含所有依赖的 dist/index.js 文件。
Q2: 本地调试时无法访问 GitHub API
A: 检查是否正确设置了 GITHUB_TOKEN 环境变量，需要包含适当的权限。
Q3: 测试覆盖率报告为空
A: 确保测试文件遵循命名约定（*.test.ts），并位于 __tests__/ 目录下。
Q4: 发布后 Marketplace 中看不到 Action
A: 确保发布时勾选了 "Publish this Action to the GitHub Marketplace"，并且 action.yml 中的元数据完整。
总结与展望
typescript-action 模板为开发者提供了一个功能完备、标准化的 GitHub Action 开发框架。通过本文的介绍，你已经掌握了从项目搭建、开发调试到发布管理的全流程。
未来，该项目可能会增加更多高级特性，如：
- AI 辅助的 Action 生成
- 与更多 CI/CD 工具的集成
- 更丰富的模板示例
无论你是 GitHub Action 新手还是资深开发者，typescript-action 都能帮助你快速构建高质量的自动化工作流，提升开发效率。
如果你觉得本文对你有帮助，请点赞、收藏并关注，以便获取更多 GitHub Action 开发技巧！
下期预告：《GitHub Action 高级技巧：事件触发与条件执行》
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
