企业官网建设流程全解析

Shiori Web 前端开发指南：基于 Vue 3 + Vite + Bun 构建书签管理器界面

【免费下载链接】shioriSimple bookmark manager built with Go项目地址: https://gitcode.com/gh_mirrors/sh/shiori

本文围绕 shiori 仓库中 webapp/README.md 展开，系统讲解新版 Web 前端的开发环境、依赖安装、本地热更新、类型检查、生产构建、单元测试与代码规范检查的完整流程。读完本文，你将掌握用 Bun 驱动 Vue 3 + Vite 技术栈开发、调试与产出 shiori 前端产物，并理解该产物如何最终被嵌入 Go 二进制中随服务一起分发。

webapp 在 shiori 中的定位

shiori 是一个用 Go 编写的简单书签管理器（Simple bookmark manager built with Go），仓库同时维护着两套前端：internal/view下的旧版模板页面，以及webapp目录下的新版 Vue 3 单页应用。从 webapp/embed.go 可以看到，前端构建产物通过 Go 的 embed 机制被打进二进制：

package webapp import ( "embed" ) //go:embed dist/index.html var Templates embed.FS //go:embed dist/assets dist/*.ico var Assets embed.FS

也就是说，webapp开发流程的终点是产出dist/index.html与dist/assets，之后由 Go 侧统一嵌入并对外提供服务。因此本 README 中的每一条命令，都直接关系到最后随 shiori 二进制一起发布的界面能否正确生成。

推荐 IDE 环境：VSCode + Volar

README 明确给出了编辑器建议：使用 VSCode 并安装Volar扩展（同时禁用 Vetur）。原因在于 Vue 3 的 SFC（单文件组件）工具链与 Vue 2 时代不同：

• 类型检查由vue-tsc取代原生tsc承担；
• 编辑器中让 TypeScript 语言服务识别.vue文件类型信息的，正是 Volar。

从 webapp/package.json 的 devDependencies 中也能印证这一点：项目同时依赖vue-tsc（^2.2.12）、typescript（~5.8.3）与@vue/tsconfig（^0.7.0）。如果你在 IDE 中看到.vue导入报类型错误或没有补全，首先应检查是否安装了 Volar 且 Vetur 已被禁用。

项目依赖与技术栈全景

先看 webapp/package.json 声明的依赖，理解开发流程背后的技术选型：

运行时依赖（dependencies）：

开发依赖（devDependencies）：vite（^6.3.6）、@vitejs/plugin-vue、vite-plugin-vue-devtools、vitest（^3.2.4）、@vue/test-utils、eslint（^9.36.0）、eslint-plugin-vue、prettier、npm-run-all2等，覆盖构建、测试、lint 与格式化全链路。

package.json 中的脚本定义如下：

"scripts": { "dev": "vite", "build": "run-p type-check \"build-only {@}\" --", "preview": "vite preview", "test:unit": "vitest", "build-only": "vite build", "type-check": "vue-tsc --build", "lint": "eslint . --fix", "format": "prettier --write src/" }

后续所有 README 命令都可以在本文件的 scripts 中找到一一对应关系。

安装依赖

bun install

仓库在 webapp/bun.lock 与 webapp/bun.lockb 之外，还保留了 webapp/package-lock.json，说明项目同时兼容 Bun 与 npm 两类包管理器。README 以 Bun 为准，如果你的环境没有安装 Bun，也可以用npm install代替，但建议遵循官方 README 使用 Bun，以保证与 lockfile 的一致性。

本地开发：编译与热更新

bun dev

该命令实际执行vite，启动带热更新（Hot-Reload）的开发服务器。Vite 的配置集中在 webapp/vite.config.ts：

export default defineConfig({ plugins: [ vue(), vueDevTools(), tailwindcss(), ], resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }, }, css: { devSourcemap: true, }, })

三个插件分别负责.vue单文件编译、Vue DevTools 调试面板和 Tailwind CSS 4 的按需扫描；@别名指向src目录，这也是源码中随处可见@/stores/auth、@/client这类导入的原因；devSourcemap开启 CSS 源码映射，方便在浏览器中直接定位到 webapp/src/assets/main.css 等源文件。

入口在 webapp/index.html，它挂载#app并加载 webapp/src/main.ts。main.ts依次注册 Pinia、Vue Router 与 i18n 后挂载应用，对应 webapp/src/App.vue 的根组件。

类型检查与生产构建

bun run build

这一步与直接vite build不同：它通过npm-run-all2的run-p并行执行type-check与build-only两个子任务——即先/同时做类型检查，再产出生产包，保证发布产物通过类型校验。

• type-check执行vue-tsc --build，参照 webapp/tsconfig.app.json、webapp/tsconfig.json 等配置，对整个src做类型检查（这正是 README 强调“用 vue-tsc 替换 tsc”的实际落点）；
• build-only执行vite build，将产物输出到dist/。

构建完成后，dist/index.html与dist/assets即被 webapp/embed.go 中声明的//go:embed指令收集。若想单独预览构建产物，可运行bun run preview（即vite preview），它会以生产模式在本地起一个静态服务用于验收。

单元测试：Vitest

bun test:unit

对应脚本为vitest。测试配置在 webapp/vitest.config.ts，它通过mergeConfig继承vite.config.ts的插件与别名配置，并补充：

test: { environment: 'jsdom', exclude: [...configDefaults.exclude, 'e2e/**'], root: fileURLToPath(new URL('./', import.meta.url)), }

• environment: 'jsdom'在 Node 环境中模拟浏览器 DOM，配合 webapp/src/assets/main.css 无关的纯逻辑与组件测试；
• 显式排除e2e/**，将端到端测试隔离到仓库根目录的 e2e/（Playwright + Go 服务端测试）体系之外，避免单元与 E2E 混跑。

ESLint 侧也通过@vitest/eslint-plugin对src/**/__tests__/*目录启用了 Vitest 专属规则，见 webapp/eslint.config.ts。

代码规范：ESLint 与 Prettier

bun lint

执行eslint . --fix。该项目使用 ESLint 9 的flat config写法（webapp/eslint.config.ts）：

export default defineConfigWithVueTs( { name: 'app/files-to-lint', files: ['**/*.{ts,mts,tsx,vue}'], }, { name: 'app/files-to-ignore', ignores: ['**/dist/**', '**/dist-ssr/**', '**/coverage/**'], }, pluginVue.configs['flat/essential'], vueTsConfigs.recommended, { ...pluginVitest.configs.recommended, files: ['src/**/__tests__/*'] }, skipFormatting, )

要点：lint 范围是全部 TS/MTS/TSX/Vue 文件，但跳过构建产物目录；vueTsConfigs.recommended让 Vue SFC 同时获得模板与脚本的类型感知；skipFormatting意味着格式化交给 Prettier 负责，即配套命令：

bun format

对应prettier --write src/，两者分工为：ESLint 管代码质量（未使用变量、类型问题、Vue 规范），Prettier 管排版风格。

前端架构速览（开发时值得关注）

在开始写业务代码前，快速熟悉 webapp/src 的目录划分，能让你更高效地使用上面的工具链：

• webapp/src/router/index.ts：路由表定义/home、/login、/tags、/folders、/archive、/settings，并在全局beforeEach守卫中结合 Pinia 的 auth store 做登录态校验；未匹配路由统一重定向到/home。除/home、/login外，各页面均使用动态import()做路由级代码分割；
• webapp/src/stores/auth.ts：以localStorage持久化 token 与过期时间，封装login、logout、validateToken、refreshToken，并通过X-Shiori-Response-Format: new请求头对接新的 API 响应格式；注意开发时其 APIbasePath写死为http://localhost:8080；
• webapp/src/stores/tags.ts：标签的增删改查与本地状态同步；
• webapp/src/utils/i18n.ts：默认语言取自浏览器（navigator.language），优先级低于localStorage中的shiori-language，语言包位于 webapp/src/locales（en/es/fr/de/ja 五个 JSON）；
• webapp/src/client：由 OpenAPI Generator 根据 docs/swagger/swagger.json 自动生成的 API 客户端（runtime.ts、apis/*、models/*），其中的 webapp/src/client/runtime.ts 提供Configuration类，用于注入 basePath、accessToken 与自定义 headers；
• webapp/src/views：七个页面视图（登录、主页、标签、文件夹、归档、设置、关于），配合 webapp/src/components/layout 下的 AppLayout、Sidebar、TopBar、LanguageSelector 等布局组件使用。

常见问题与注意事项

1. 改完代码要跑bun run build：本地bun dev不会修改dist/，只有构建后才能通过go:embed打进 Go 二进制。若修改了前端却看不到服务端界面变化，多半是忘了重新构建。
2. 开发期 API 地址：当前 webapp/src/stores/auth.ts 等 store 中basePath固定为http://localhost:8080，本地联调时需保证 shiori 服务监听在 8080 端口；部署到其他地址需按实际环境调整。
3. 编辑器类型提示不生效：确认已安装 Volar 并禁用 Vetur，同时建议直接打开webapp/目录而非仓库根目录，以便 VSCode 正确加载根级 tsconfig。
4. 锁文件一致性：项目同时存在 Bun 与 npm 两套 lockfile，建议统一使用 README 推荐的bun install，避免两套依赖树不一致导致 CI 与本地行为不同。
5. 测试隔离：Vitest 配置已排除e2e/**，单元测试与 e2e/ 的端到端测试（Playwright + Go 容器）彼此独立，跑bun test:unit前无需启动任何服务。

综上，webapp的开发闭环可以概括为：bun install（装依赖）→bun dev（迭代开发）→bun test:unit+bun lint+bun format（质量保障）→bun run build（产出dist/供 webapp/embed.go 嵌入）。掌握这条链路，你就能独立参与 shiori 新版界面的开发与构建发布。

【免费下载链接】shioriSimple bookmark manager built with Go项目地址: https://gitcode.com/gh_mirrors/sh/shiori